Output Translation

We’re hosting a workshop with CustomInk and FluidHire to reach out to tech workers in the federal IT space.  We think a lot of them would be happier working in DC’s busy commercial tech scene, especially with the sequester.  Here’s a quick summary:

http://www.bizjournals.com/washington/blog/techflash/2013/04/qa-charlie-reverte-addthis-vp-of.html?page=all

The event is tomorrow night, sign up here: http://govtocom.eventbrite.com/

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

• Endpoints used to create, list, and search for entities should look like directories, e.g. /users
• Use a plural noun so it feels like a directory of users, not a user controller
• Endpoints used to read, update, and delete individual entities should look like files, e.g. /users/charlie

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

• Either apples, or oranges, or a list of oranges, don’t mix them up
• File-looking endpoints should return individual entities
• Directory-looking endpoints should return lists of entities

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

• Consistent response type per endpoint simplifies deserialization for clients, no switching needed
• Once you agree on a contract it’s easy to mock up with static files on a server
• Clients can start working with your mockup before your code is finished

Example Operations on Endpoints that look like Files

Read

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

Update

PUT|PATCH /users/charlie
[password=1111]

Delete

DELETE /users/charlie

Example Operations on Endpoints that Look Like Directories

List

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

Search

GET /users?q=cha

Create

POST /users
{username=charlie&password=1234}
201 CREATED
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:

http://api.example.com/users/charlie.json

• Not pure REST but it makes your API easier for devs to poke with curl and the browser. Easier to use means better adoption!
• Friendlier on stupid caches that improperly handle headers since the endpoint always sends back the same bytes (within the ttl)
• You can use .html (or no extension) to request the web representation and serve your API and web views with the same controller logic (though this can turn into a rabbit hole)

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

http://q.addthis.com/feeds/1.0/trending.json?pubid=atblog

• feeds.war is the webapp and 1.0 is the version of the released artifact (which is 1.0.3 internally)
• Version numbers should correspond to deployable artifacts so they’re easier to manage
• You’ll need to keep old versions online in real-world use cases

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).

• You’ll need to define a standard error response envelope that they can switch on to check for errors and extract the reason. It will get messy for them and they will lose a lot of the benefits of this design.
• Anyone have better ideas here?

This is kind of a note-to-self – Schecter Elite 5-string basses need extra long strings, I tried searching for a part number but google couldn’t find one.  So I called Schecter and Sergio told me:

Your instrument was factory strung with D’Addario EXP170-5SL strings.  The individual string gauges (from low to high) are:

B.-130  E-.100  A-.080  D-.065  G-.045

So there, now google knows.  thanks Sergio!

These had better be good. Never doing this again.

I dry fit the case and cut the racks for the bottles and glasses. And I measured once and cut twice and paid the price. Otoh, spanish cedar smells sooo good, they should bottle that stuff.

I think I only started this project as an excuse to play in solidworks again. If you don’t have a space navigator you need one, trust me: http://www.3dconnexion.com/products/spacenavigator.html