REST API Best Practices: a REST Cheat Sheet

I'm interested in REST API design and identifying the best practices for it. Surprisingly, a lot of APIs that claim to be RESTful, aren't. And the others all do things differently. This is a popular area, though, and some best practices are starting to emerge.  If you're interested in REST, I'd like to hear your thoughts about best practices.

REST is not simply JSON over HTTP,  but most RESTful APIs are based on HTTP. Request methods like POST, GET, PUT and DELETE are used to implement Create, Read, Update and Delete (CRUD) operations. The first question is how to map HTTP methods to CRUD operations.

To start, here's a "REST API Design Cheat Sheet" that I typed up and pinned to my wall. Its based on the book "REST API Design Rulebook", and the HTTP RFC. I think it reflects standard practice. There are newer and better books on the subject now, but this list covers the basics of HTTP requests and response codes used in REST APIs.

Request Methods

• GET and POST should not be used in place of other request methods
• GET is used to retrieve a representation of a resource
• HEAD is used to retrieve response headers
• PUT is used to insert or update a stored resource
• POST is used to create a new resource in a collection
• DELETE is used to remove a resource

Response Status Codes

• 200 "OK" indicates general success
• 200 "OK" shouldn't be used to return error messages
• 201 "Created" indicates a resource was successfully created
• 202 "Accepted" indicates that an asynch operation was started
• 204 "No Content" indicates success but with an intentionally empty response body
• 301 "Moved Permanently" is used for relocated resources
• 303 "See Other" tells the client to query a different URI
• 304 "Not Modified" is used to save bandwidth
• 307 "Temporary Redirect" means resubmit the query to a different URI
• 400 "Bad Request" indicates a general failure
• 401 "Unauthorized" indicates bad credentials
• 403 "Forbidden" denies access regardless of authentication
• 404 "Not Found" means the URI doesn't map to a resource
• 405 "Method Not Allowed" means the HTTP method isn't supported
• 406 "Not Acceptable" indicates the requested format isn't available
• 409 "Conflict" indicates a problem with the state of the resource
• 412 "Precondition Failed" is used for conditional operations
• 415 "Unsupported Media Type" means the type of payload can't be processed
• 500 "Internal Server Error" indicates an API malfunction

A note about the PATCH method. There are good reasons to consider using the HTTP PATCH method for partial updates of resources, but because it's not supported everywhere, and because there are workarounds, I haven't added it to my cheat sheet yet.

Other Posts in this series

REST API Best Practices 2: HTTP and CRUD
REST API Best Practices 3: Partial Updates - PATCH vs. PUT
REST API Best Practices 4: Collections, Resources and Identifiers

Kasa

Kasa  © 2010 Darren DeRidder.
Umbrella detail, Kinosaki, Japan

When Agile Went Off the Rails

Whenever I hear a company say "We follow an agile development process", I can't help but wince a little. The core ideas of agile development are excellent, but somewhere along the way it accumulated quite a lot of codified process, and became its own formal methodology - almost the same thing the Agile Manifesto was trying to counteract. It's not too surprising, since the agile manifesto didn't prescribe any particular project management methodology for implementing its guidelines. So naturally it wasn't long before management professionals began to formalize agile philosophy into a methodology of their own.

Now one of the original authors of the Agile Manifesto has come out with a piece, originally titled "Time to Kill Agile", in which he makes this point that a formal methodology runs counter to the original goals of the agile development concept. Dave Thomas has been hugely influential in the software development field. Aside from being one of the authors of the agile manifesto, he's written a lot of other stuff, and he's the guy who coined the phrases "code kata" and "DRY" (Don't Repeat Yourself - the maxim developers follow to effectively organize their code).  He later renamed the piece "Agile Is Dead (Long Live Agility)!", which is a better reflection of his current thinking on Agile processes vs agile development's underlying goals.

Being a critic of Agile is risky; in many cases it seems to have improved the effectiveness of teams a lot. It's working for a lot of people, and they like it.

But having one of the original authors of the Agile Manifesto come out with this kind of criticism of agile methodology makes a certain amount of healthy skepticism seem appropriate.

Agile software development, according to Dave Thomas, can't be implemented as a set of methodologies, and the managers, consultants and companies that have sprung up around Agile have shown a certain level of disregard for what the authors of the Agile Manifesto intended in the first place.

Dave Thomas has some good advice for teams that want to develop software with agility. He advocates an iterative approach to development, and choosing options that enable future change. He recommends thinking of "agile" in the form of an adverb (agilely, or "with agility"). Programming with agility. Teams that execute with agility.

I've found that when it comes to managing a project, simple is usually better. What's worked best in my experience is, in a nutshell, to simply encourage communication. Make sure everyone understands the overall objective, how they can contribute to it, what progress has been made and what challenges remain, and importantly, give everyone the opportunity to have their work fully recognized and appreciated on a regular basis. Given the opportunity to work on a challenging project and the chance to have their contributions seen and appreciated by colleagues, most developers will bend over backwards to do their best.

One technique I found effective was a brief (timed with a hard stop) Monday morning meeting where we laid out the objectives for the week ahead, a quick information-gathering hike around the office at the end of the week, and an email re-cap on Friday afternoon highlighting the team's progress. Showing the percentage-towards-completion of major tasks was also a big motivator, as developers began to take pride in seeing their areas of responsibility make steady, visible progress towards completion.  We didn't formalize or get locked into one way of doing it, so when our company got acquired and our management structure changed, we adapted pretty easily.

Perhaps this isn't too far away from the way agile methodology is practiced "by the book". Regardless of the methodology, it's worth noting that the Agile Manifesto wasn't really a call to implement any particular process. It had broader goals in mind:

• People over processes.
• Working software over documentation.
• Collaboration over contracts.
• Adaptability over planning.