1. URLs should reference entities (nouns) and not actions (verbs).

   • The action or verb should be defined by HTTP (GET, PUT, POST, DELETE)

2. Entity names in URLs should be plural.

   • There are exceptions to this rule (e.g. when the entity name is not an actual entity that can be listed), but the exceptions should be rare.

3. Use GET for listing entities or reading a single entity.

   • e.g. GET /entities returns a list of entites (list may be wrapped)
   • e.g. GET /entities/123 returns a single entity with ID 123

4. Use PUT for idempotent entity changes.

   • An operation is considered idempotent if it has the same result regardless of how many times it is executed. Think of idempotent as assignment or overwriting, e.g. x = 1 or Map.put
   • Generally applies to update operations
   • e.g. PUT /entities/123 updates entity with ID 123

5. Use POST for non-idempotent entity creations/changes.

   • An operation that is not idempotent is one that causes changes each time it is called, e.g. x++ or List.add
   • Generally applies to create operations
   • e.g. POST /entities creates a new entity

6. Use DELETE for deleting entities.

   • e.g. DELETE /entities/123 deletes entity with ID 123

7. Entity names should correspond to a particular object type.

   • This means that return types should be the same when the last entity name in a URL is the same.
   • e.g. /burgers and /burgers?meat=beef and /restaurants/123/burgers should all return the same object type.

8. The response body for a GET (singular entity) should be a valid request body for a PUT at the same URL.

   • e.g. If Fleet object type is returned from GET /fleets/123, then Fleet object type should be accepted by PUT /fleets/123 (assuming that an update is supported)

9. PUT and POST should accept data as request body in proper content type.

   • i.e. Creations should be accomplished by POSTing JSON or XML (instead of name-value pairs or URL-encoded forms) in the request body.

10. Nested paths should be reserved for entity relationships or context, not for categorization.

    • This means (1) a nested path should always contain an ID of the parent entity and (2) any level of a nested path should be a valid URL.
    • e.g. /admin/messages should be /adminmessages or just /messages

11. Nested paths should probably be limited to 1 or 2 levels.

    • It’s generally easier to switch context than it is to maintain a full hierarchy with parent IDs.
    • e.g. /distributors/123/accounts/456/fleets/789/mobiles/321/pins/6 is certainly ridiculous when /mobiles/321/pins/6 is specific enough to get the same thing.

12. Filtering, sorting, and paging an entity list should be accomplished via URL parameters.

    • e.g. /mobiles?fleetId={fleetId}&page={num}&pageSize={num}&sort={propertyName}

13. Use consistent entity/parameter names when possible.

    • Check existing API or other designs when you have a question about a name that may be used elsewhere.
    • It’s ok to support multiple names of the same thing for the same call, but be consistent.
    • e.g. If ?lat={lat}&lon={lon} is already used somewhere, then don’t use ?latitude={lat}&longitude={lon} or ?lat={lat}&lng={lon} unless you already support the first option.

14. Err on the side of flexibility.

    • e.g. Support both /fleets/123/mobiles and /mobiles?fleetId=123

15. Version your API via the URL.

    • This makes it easy for clients to ask for a specific version and helps you to segregate differences cleanly.
    • e.g. Version 1 of your API should be available under /v1 (or similar) with URLs like /v1/contacts and /v1/teams/5/members. Version 2 would then be available under /v2.

16. Use appropriate HTTP status codes for error responses.

    • e.g. An invalid request should return a status code in the 400s, and an unexpected server error should return a status code in the 500s.

17. All errors returned should use the same data structure in the body of the response.

    • When errors occur, you need to give your client enough info about the error to know what went wrong and how to fix it - as long as the info does not present a security vulnerability.
    • This means an invalid request like GET /events?occurringBefore=never does not return a response with a list of Event objects, it returns a response with an Error object (stating that "never" is not a valid value for the "occurringBefore" param).
    • Your Error response should probably include fields like an application-defined code (to help distinguish between specific problems that might return the same HTTP status), a message for the client program (does not need to support i18n), and a userMessage for the end-user (does need to support i18n).

I also highly recommend dogfooding your own API (i.e write and use your own client for your API). Doing so will certainly help you weed out the confusing and difficult parts of your API.

Obviously, these guidelines don’t cover everything (e.g. consistent data structures across all lists, conventional formats for certain datatypes, how to do authentication e.g. OAuth, etc), but these are battle-tested and should serve as basic rules your API should conform to. As you're building and testing your API, you'll undoubtedly encounter questions that are not addressed here. When that happens, discuss with your team and add to your adopted conventions as necessary.

(Originally written Monday, February 25th, 2013)

Reviewing code is a necessary part of software development, but I've found that many developers either don't know how to do good code reviews or just don't do it effectively.

Here's the quick-and-dirty list I usually give my software teams. Answer these questions while reviewing someone else's code and it will eventually become second-nature to you.

First the low-level:

• Is the code syntactically and logically correct?
• Is the code actually doing what it’s intended to do?
• Does the code use resources efficiently (e.g. db call, memory consumption, etc)?
• Is the code reasonably documented?
• Is the code too complicated or confusing to follow?
• Is there a better way of doing what the code is doing?

Then the high-level:

• Does the code produce the desired functionality?
• Does the code directly or indirectly introduce problems for other/existing/transitive functionality?
• Does the code follow conventions or precedents of similar existing functionality?
• Is this the best place to put this logic?
• Does the code smell (i.e. does it make you uneasy, even if you can’t exactly say why)?

All of these can pretty much be summed up by If I were implementing this functionality, is this the way I'd write my code?

Obviously it takes a little experience to know how to answer these questions, but that will come with time and practice.

Happy reviewing!

(Originally written Wednesday, March 13th, 2013)

It didn't come as any big surprise since I knew of several other things leading up to this point, but I had no idea if his timeline was several months out or only a few weeks away. Turns out to be even shorter than that. He'll be gone, leaving not only this company but also this state, in just a week and a half.

Today, after our weekly team lunch, he came to my office and told me he had accepted an offer. We talked about his new opportunity, what the interview process was like, how quickly everything had happened, how much we have enjoyed working with each other and have learned from each other, and covered some logistics. Then he gave his notice to our VP and told the rest of the team. And that was that.

Now that it's official, the realization is starting to sink in. Some of the things I have anticipated for a long time are finally here, and things will be changing very soon. If I don't get my bearings and hop aboard a car, I'll miss the train. Dave's exit is now a catalyst for my own.

About Dave, though...

It's tough to know what to say. All at once I'm sad to see him go, excited for his opportunities, discouraged about losing his day-to-day friendship, and proud of his well-earned success.

He's the type of person that can learn any new technology in less than a day and can master it in a week. Be it a Node.js app backed by Mongo, a Spark app using Spring Integration for messaging, an Android app consuming a REST API, or loading a bunch of data into ElasticSearch and building a find-anything UI on top of it, Dave can pump out POCs like nobody's business. (Not to mention, he can fine-tune a Windows registry like a musical instrument!)

He really is one of the best software developers I've ever met, but more than that, he's a great guy with a positive, matter-of-fact attitude that made our team and my life better. He always looked forward to a challenge and never said no to, or complained about, any assignment ever given. He provided invaluable insight, was always tuned-in to his fellow team members, and constantly provided ideas for improving practices and processes to make everyone more productive. I've had the privilege of working and learning alongside him for the past 3 years, and I've really seen him grow into a great team leader.

And, above all that, I just plain like him.

One thing you should know about Dave is that he's a pretty healthy guy too, so he drinks water whenever we go out to eat. Our team goes out to lunch together at least once a week, usually on Fridays, and Dave and I would grab lunch together frequently beyond that. Out of the hundreds of times we've eaten together, I don't think I've ever seen him order anything to drink besides water for lunch. I, on the other hand, usually order overpriced soda. But, on several occasions, Dave has been snubbed with my drink on his bill.

The first time it happened, it was funny. The second time it happened, it was just strange. The third time, I suspect conspiracy. But it really has happened so often that it's now just a regular thing. It's almost weird if Dave doesn't end up paying for my drink. But, of course, Dave's the type of guy who rolls with the punches and happily pays on my behalf without any expectation of reimbursement. I literally probably owe him about $40 worth of non-alcoholic beverages.

So, Dave, if you're reading this, thanks for the countless drinks you've bought me, and thanks for making my job and life a little sweeter every day for the past few years. You're a class act, and I'm gonna miss you. I really do wish you and your wife all the best. If you ever need anything or just want to shoot the breeze, all you have to do is call. I'll keep your tab open at the usual spots.

So long, and thanks for all the drinks.

P.S. You can read Dave's old blog here.