Output Translation

URL Design for RESTful Web Services

This is a cross-post of a guest post I did for APIUX.  Click here for the original..

URL design discussions for RESTful web services often degrade into debates over pluralization and parameter names. There are a couple of principles I like to use to keep things simple.

1) Using your API should feel like using a filesystem

2) All calls to a given endpoint should return the same type

We may be bikeshedding here but I think your API will be more intuitive to newcomers if you model it this way.

Example Operations on Endpoints that look like Files


GET /users/charlie
200 OK
{username: charlie, state: VA}


PUT|PATCH /users/charlie


DELETE /users/charlie

Example Operations on Endpoints that Look Like Directories


GET /users?start=40&count=20
200 OK
[{username: charlie, state: VA}, ...]


GET /users?q=cha


POST /users
Location: /users/charlie

Directory endpoints are supposed to return lists (or nothing).  So send back a pointer to the new user record, rather than the user data itself.

POST /users/charlie

Also ok IFF you allow clients to generate entity ids

Serious Bikeshedding

Here’s other stuff I like:

Use a filename extension instead of the Accept header to express the response format:


Another vote against the Accept header: version your endpoints in the URL, at web-application level:


Dropwizard has a nice model for organizing your projects.

Some javascript/flash API consumers will pressure you to add a suppress_response_codes parameter and always send them a 200. You’ll hate it but will end up giving in (just wait).

Exit mobile version