What is a RESTful API? (notes)

It's in job ads everywhere: employers looking for developers with experience in building RESTful APIs. What does REST mean and what does it take for an API to be considered RESTful?

REST is a way to build a web service. Think of a web service as a common platform that allows communication between client and server applications. So, REST is just a way to do that! It's an architectural style, and it stands for Representational State Transfer. Roy Fielding, who gave us REST, explains it like this:

"REST is intended to evoke an image of how a well-designed web app
behaves: A network of web pages (a virtual state-machine) where the
user progresses through an application by selecting links (state
transitions), resulting in the next page (representing the next
state of the application) being transferred to the user and rendered
for their use."

Here is a real-life example:

REST is defined by six constraints (constraints are just design decisions):

  1. Client-server constraint
    • Client and server are separated
    • Client shouldn't be concerned with how data is stored or how representation is generated
    • Server shouldn't be concerned with user interface, or user state, or anything related to how client is implemented
    • What's the why?: Client and server can thus evolve separately

  2. Statelessness constraint
    • The state necessary to handle any request is contained within the request itself
    • Requests cannot take advantage of any stored context on the server; session state is kept entirely on the client, via caching
    • What's the why?: Visibility, reliability, scalability

  3. Cacheable constraint
    • Each response must explicitly state if it can be cached or not
    • If response is cacheable, then client cache is given right to reuse that response data for later, equivalent requests

  4. Layered system constraint
    • Restricts knowledge to a single layer
    • Solution can be comprised of multiple layers
    • Client cannot tell what layer it's connected to, or if it's connected to an intermediary layer along the way

  5. Code on demand constraint (optional)
    • Server can extend or customize client functionality
    • Example: if client is a web app, server (api) can transfer JS code to client to extend its functionality

  6. Uniform Interface Constraint
    • API and API consumers share one single technical interface. Since typically working with HTTP protocol, interface should be seen as a combination of resource URIs, HTTP methods, and HTTP media types
    • Subconstraints:
      • Identification of resources
        • Individual resources are identified in requests using URIs, and those resources are conceptually separate from their representation
        • Representation is the JSON or XML sent back in the response
      • Manipulation of resources through representations
        • Representation plus metadata should be sufficient information to modify or delete the resource (permissions assumed)
      • Self-descriptive messages
        • Each message must include enough information to describe how to process the message

REST often uses HTTP protocol, but doesn't have to. What is http protocol?

What are the http methods?

-> Different actions can use the same URI - it's up to the verb(method) to decide what happens.

  1. GET
    • Used for reading resources
    • No request payload
    • Sample URI: api/employees, api/employees/{employeeId}
    • Response payloads: employees collection, single employee
  2. POST
    • Used for creating a resource
    • Request payload: single employee
    • Sample URI: api/employees
    • Response payload: single employee
  3. PUT
    • Used for updating resources (full updates)
    • Request payload: single employee
      • Should include all fields related to the employee. If a value is missing, default values should apply
    • Sample URI: api/employees/{employeeId}
    • Response payload: single updated employee or empty
  4. PATCH
    • Used for partial updates
    • Request payload: JSON patch document on employee
    • Sample URI: /api/employees/{employeeId}
    • Response payload: single updated employee or empty
    • Used to remove a resource
    • Request payload: none
    • Sample URI: /api/employees/{employeeId}
    • Response payload: none
  6. HEAD
    • Identical to GET, but no response body should be returned
    • Used to obtain info on resource, like testing if a resource exists
    • Represents a request for info about the communication options available on that URI
    • Will tell us whether or not we can GET/POST/DELETE the resource
    • Options are typically in response headers

What are status codes?

-> Status codes tell the consumer of the API whether or not the request worked out as expected, and what is responsible for a failed req

  1. Level 200: Success
    • 200: OK
    • 201: Created (resource created)
    • 204: Request OK, but no content returned
  2. Level 400: Client mistakes
    • 400: Bad request, req sent to the server is wrong
    • 401: Unauthorized, no or invalid authentication details were provided
    • 403: Forbidden, authentication succeeded but user doesn't have access to resource
    • 404: Requested resource doesn't exist
    • 405: Method not allowed, like trying to send a req to a URI with POST method, but only GET is implemented
    • 406: Not acceptable, a consumer might request XML media type while API only supports JSON
    • 409: Conflict, like a conflict in request vs current state of resource (i.e. editing a version of a resource which has been renewed since editing started); also used when trying to create a resource that already exists.
    • 415: Unsupported media type, sort of opposite of 406
    • 422: Unprocessable entity, semantic mistakes, usually related to validation
  3. Level 500: Server mistakes
    • 500: Internal server error, server made the mistake and client can't do anything about it

*Other things that are important:

Naming conventions

Unchanging URIs

Richardson Maturity Model

-> Grades APIs by their RESTful maturity

  1. Level 0: The swamp of plain old XML
    • HTTP protocol is used for remote interaction, but the rest of the protocol isn't used how it should be.
    • Examples are SOAP or other RPCs
    • Basically, HTTP is only used to transport
    • Example: Sending a POST req to /host/api to get info, and sending a POST req to same URI for a real POST. Info related to the resource you want is sent within XML body.
  2. Level 1: Resources
    • Each resource is mapped to a URI, but still only one HTTP method used.
    • Example: /host/api/employees URI, and /host/api/employees/id URI, but API only uses a POST method
  3. Level 2: Verbs
    • Correct HTTP verbs are used
    • Correct status codes are used
  4. Level 3: Hypermedia
    • Level 3 is the bare minimum for an API to be considered truly RESTful
    • API supports HATEOAS
    • Example: a GET req to /api/employees would return a list of employees and code/links that drive application state (hypermedia)

To be truly RESTful, must implement HATEOAS: