paskvilwiki

up: programming

RESTful APIs

last updated 2014-06

WIP - check for updates later

this section is about RESTful web-based APIs

take this section with a pinch of salt. also, see the disclaimer

what is RESTful?

there is no standard for what a REST API is (it's an architectural style, not a protocol), but there is a precedent on most of the functional specs. this list presents my preferences regarding the "gray" areas of the spec

representational state transfer (REST) is a way to create, read, update or delete information on a server using simple HTTP calls

REST has strict separation of clients and servers, by a uniform interface

REST is stateless - each request from any client contains all the information necessary to service the request, and session state is held in the client. an important exception to this rule is the authentication session that is stored on servers

REST is cacheable. responses must therefore, implicitly or explicitly, define themselves as cacheable, or not, to prevent clients reusing state or inappropriate data in response to further requests. well-managed caching partially or completely eliminates some client-server interactions, further improving scalability and performance

REST has a uniform interface:

  • resources/entities are uniquely identified by URIs. the resources themselves are conceptually separate from the representations that are returned to the client (JSON, XML, ...)
  • a client that holds such a representation of a resource (including any metadata attached) has enough information to modify or delete this resource
  • each message includes enough information to describe how to process the message

web-based REST APIs typically comply to:

  • having a base URI, such as http://example.com/resources/
  • using an Internet media type for the data - this is often JSON but can be any other valid Internet media type (e.g. XML, Atom, microformats, images, etc.)
  • using standard HTTP methods (e.g., GET, HEAD, POST, or DELETE)
  • using hypertext links to reference state
  • using hypertext links to reference related resources

interface recommendations

  • use POST for both entity creation and update

    typically, REST APIs are expected to use POST for element creation, and PUT for element update. i'm not a big supporter of this - analogous to the majority of programming (scripting) languages, where you use the same assignment operator for both variable creation and updating, you should use the same HTTP method

    also, you'll avoid discussions about what is entity creation and what is update, esp. in scenarios where you want to allow creation and updates of sub-entities, where either of those can be viewed as an update of the entity itself

    also, note that often REST is not supposed to allow access to sub-entities, but it makes life so much easier, and costs you less traffic

  • versioning - depends on the expected lifetime of the API

  • access to sub-entities

  • pagination and other non-entity specific parameters as GET parameters

  • HEAD on entities; GET on collections is a list; POST on a collection creates an entity, POST on an entity updates it; use OPTIONS for mature stages, on the * ID

disclaimer

this list is by no means supposed to represent any "standard view" of REST APIs

it does not represent opinions of any of the companies i work(ed) with

it is my personal checklist when designing interfaces. many points depend only on your taste

some of the opinions are even "not really REST" but make life easier for either you as a backend dev, or for your consumers, or both

HTTP response codes

this is not a definitive list, it's just stuff i use the most, and always forget which is which

  • 100 - Continue
  • 200 - OK
  • 201 - Created
  • 202 - Accepted
  • 204 - No Content
  • 301 - Moved Permanently
  • 302 - Found (i typically use this instead of the 307 "Temporary Redirect")
  • 304 - Not Modified
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 405 - Method Not Allowed (using GET on POST calls, etc. - must include the Allow response header)
  • 406 - Not Acceptable (mismatch of the response format and the Accept headers)
  • 500 - Internal Server Error
  • 501 - Not Implemented
  • 503 - Service Unavailable