Common Mistakes in RESTful API Design and Best‑Practice Guidelines

In many micro‑service projects, developers often design API endpoints in inconsistent ways, leading to non‑RESTful interfaces. This article collects typical pitfalls and shows how to correct them according to RESTful principles.

Typical Wrong Patterns

1. Querying a single object with a verb in the path: GET /app/getImportantApp 2. Listing resources with a generic path: GET /app/list 3. Saving an object using a verb endpoint: POST /app/save 4. Deleting an object with a POST verb: POST /app/delete 5. Updating objects via a batch endpoint: POST /app/batchUpdate These designs misuse HTTP methods and embed actions in the URI, which contradicts RESTful architecture where each resource should be represented by a noun.

Misuse #1 – URI Should Use Nouns, Not Verbs

Resources are nouns; for example, a product list should be accessed via /products instead of /getProductList. Actions that cannot be expressed by standard HTTP verbs should be modeled as resources, e.g., /users/1/products rather than /users/1/getProducts.

Misuse #2 – Version Numbers in the URI

There are three viewpoints on placing version numbers in the URI. Some prefer /products/v1 for backward compatibility, while others argue it mixes versioning with resource identity. A recommended approach is to use the Accept header to specify the version, e.g.: Accept: vnd.example-com.foo+json; version=1.1 When versioning in the path is needed, keep it simple and place it after the module, such as /api/user/v2.

Misuse #3 – Case Sensitivity and CamelCase in URLs

URLs should be lowercase and use hyphens for readability. Replace POST /orderItems/v1/1001 with POST /orders/v1/items/1001 or /order-items/v1/1001.

Best‑Practice Checklist

Use nouns (plural) for resources, e.g., /users, /products.

Map HTTP methods correctly: GET for retrieval, POST for creation, PUT for updates, DELETE for removal.

Express relationships with sub‑resources, e.g., GET /cars/711/drivers/.

Declare request/response formats with Content-Type and Accept headers.

Provide filtering, sorting, field selection, and pagination via query parameters ( ?color=red, ?sort=-manufacturer,+model, ?fields=id,model, ?offset=10&limit=5).

Include total count in a custom header ( X-Total-Count) and pagination links using the Link header.

Version APIs explicitly, using simple numeric versions (e.g., /api/v1).

Return appropriate HTTP status codes and detailed error bodies, for example:

{
  "errors": [
    {
      "userMessage": "Sorry, the requested resource does not exist",
      "internalMessage": "No car found in the database",
      "code": 34,
      "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"
    }
  ]
}

When only POST and GET are supported by a proxy, use the X-HTTP-Method-Override header to tunnel other methods.

Summary

Adhering to these RESTful conventions yields clean, maintainable APIs that are easier to version, cache, and evolve, avoiding the pitfalls of verb‑laden, version‑confused, or case‑inconsistent endpoint designs.