RESTful API design best practice & rules

RESTFul: RESTful describes an API that follows the architectural principles of REST (Representational State Transfer). It is a style of designing web APIs so they are Simple , predictable, scalable and easy to use.

URI design rules

Rule: Forward slash / must be used to indicate hierarchical relationship Rule: Trailing forward slash / should not be used in URIs Rule: Hyphens — should be used to improve readability of URIs Rule: Underscore _ should not be used in URIs Rule: Lower case letters should be preferred in URI path Rule: File extensions should not be included in URIs Rule: A singular noun should be used for document names Rule: A plural noun should be used for collection names

❌ Bad
/createUser 
/getUserInfo
/updateUserPassword

✅ Good
/users
/users/{id}
/users/{id}/password

URLs = nouns 
HTTP methods = verbs

Rule: A plural noun should be used for store names Rule: A verb or verb phrase should be used for controller names Rule: Variable path segments may be substituted with identity-based values

http://api.soccer.restapi.org/leagues/{leagueiD}/teams/{teamId}/players/{playerId}

Rule: CRUD function names should not be used in URIs

✅ For example, this API interaction design is preferred DELETE /users/1234

❌ The following anti-patterns exemplify what not to do: DELETE /deleteUser/1234

Rule: The query component of a URI may be used to filter collections or stores Rule: The query component of a URI should be used to paginate collection or store results

Interaction design with Http

Rule: GET and POST must not be used to tunnel other request methods Rule: GET must be used to retrieve a representation of a resource Rule: HEAD should be used to retrieve response headers Rule: PUT must be used to both insert and update a stored resource Rule: PUT must be used to update mutable resources Rule: POST must be used to create a new source in a collection Rule: POST must be used to execute controllers Rule: DELETE must be used to remove a resource from its parent Rule: OPTIONS should be used to retrieve metadata that describes a resource’s available interactions

Rule: Use HTTP status code properly 👍 Success

• 200 OK for non specific success
• 201 Createdindicates sucessful resource creation
• 202 Acceptedindicates successful start of an async action
• 204 No Contentwhen the response body is intentionally empty

⚠️ Client error

• 400 Bad Request for non specific failure
• 401 Unauthorized(no/invalid token)
• 403 Forbidden(valid token but not allowed)
• 404 Not Foundwhen a client’s URI cannot be mapped to a resource
• 406 Not Acceptable used when requested media type cannot be served
• 409 Conflict (duplicate email, etc)

💥 Server errors

• 500 Internal Server Error should be used to indicate API malfunction
• 503 Service Unavailable

Metadata design

Rule: Content-type must be used Rule: Content length should be used Rule: Last-Modified should be used in responses Rule: ETag should be used in responses Rule: Stores must support conditional PUT requests Rule: Location must be used to specify the URI of a newly created resource Rule: Cache-Control, expires and date response headers should be used to encourage caching Rule: Caching should be encouraged Rule: Expiration caching headers should be used with 200 (“OK”) responses

Error representation

Rule: A consistent form should be used to represent errors

Versioning

Never break existing clients.

✅ Good

/v1/users
/v2/users

❌ Bad

/users?version=1

Support filtering, sorting, and pagination

User query parameters for these features for example:

Filtering

/products?category=phone&brand=apple

Sorting

/products?sort=price&order=asc

Pagination

/products?page=2&limit=20

Use proper authentication

Prefer industry standards

• OAuth 2.0
• JWT (common for mobile/web)
• API keys (for internal/low-risk scenarios) Authentication header:

Authorization: Bearer <token>

Make APIs idempotent

idempotent means: same request repeated -> same result

• GET -> idempotent
• PUT -> idempotent
• DELETE -> should be idempotent

POST is the only one that is not idempotent