Skip to content

Instantly share code, notes, and snippets.

@lgmkr

lgmkr/REST & Hypermedia APIs.md

Forked from 0xdevalias/REST & Hypermedia APIs.md
Last active August 31, 2015 16:36
Show Gist options
  • Save lgmkr/3fdd7e67ddd75bb94b10 to your computer and use it in GitHub Desktop.
Save lgmkr/3fdd7e67ddd75bb94b10 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
REST & Hypermedia APIs.md

Figure out a good standard for how to use the HTTP response codes in a 'truly RESTful' (Now called 'Hypermedia API' apparently) way.

Summary

  • HTTP Methods (Verbs)
    • Spec: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
    • OPTIONS: Display which HTTP methods can be called on a resource.
    • GET: Just get a resource.
    • PUT: Update a resource
    • PATCH: Partial update of a resource (not universally supported)
    • DELETE: Delete a resource
    • POST: Create a resource
  • HTTP Status (Response) codes
    • Twitter: https://dev.twitter.com/docs/error-codes-responses (This is the most acceptable and comprehensive list I have found)
      • Potentially adding:
        • 10.2.2 201 Created: The request has been fulfilled and resulted in a new resource being created
        • 10.2.3 202 Accepted: The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon.
        • 10.2.5 204 No Content: The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.
        • 10.4.3 402 Payment Required
        • 10.4.6 405 Method Not Allowed **** 10.5.2 501 Not Implemented: The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource. *** Status codes, error messages, error codes
  • HATEOS (link your resources) ** http://en.wikipedia.org/wiki/HATEOAS

Books

Further Readings (If Interested)

MailGun http://documentation.mailgun.com/api-intro.html#errors

Code Description 200 Everything worked as expected 400 Bad Request - Often missing a required parameter 401 Unauthorized - No valid API key provided 402 Request Failed - Parameters were valid but request failed 404 Not Found - The requested item doesn’t exist 500, 502, 503, 504 Server Errors - something is wrong on Mailgun’s end

HAL - Hypertext Application Language

Don't need to specifically implement this to the letter, but it gives some good ideas/examples of the hypermedia linking/discoverability idea.

http://www.amazon.com/Building-Hypermedia-APIs-HTML5-Node/dp/1449306578

With this concise book, you’ll learn the art of building hypermedia APIs that don’t simply run on the Web, but that actually exist in the Web. You’ll start with the general principles and technologies behind this architectural approach, and then dive hands-on into three fully-functional API examples.

Too many APIs rely on concepts rooted in desktop and local area network patterns that don’t scale well—costly solutions that are difficult to maintain over time. This book shows system architects and web developers how to design and implement human- and machine-readable web services that remain stable and flexible as they scale.

  • Learn the H-Factors for representing application metadata across all media types and formats
  • Understand the four basic design elements for authoring hypermedia types
  • Convert a simple read-only XML-based media type into a successful API design
  • Examine the challenges and advantages of designing a hypermedia type with JSON
  • Use HTML5’s rich set of hypermedia controls in the API design process
  • Learn the details of documenting, publishing, and registering media type designs and link-relation types

Github

http://developer.github.com/v3/

http://developer.github.com/v3/media/

  • Custom media types are used in the API to let consumers choose the format of the data they wish to receive.
  • Also includes versioning/etc

http://developer.github.com/v3/#client-errors

  • Sending invalid JSON will result in a 400 Bad Request response.
  • Sending the wrong type of JSON values will result in a 400 Bad Request response.
  • Sending invalid fields will result in a 422 Unprocessable Entity response.

http://developer.github.com/v3/#http-verbs

Verb Description HEAD Can be issued against any resource to get just the HTTP header info. GET Used for retrieving resources. POST Used for creating resources, or performing custom actions (such as merging a pull request). PATCH Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests. PUT Used for replacing resources or collections. For PUT requests with no body attribute, be sure to set the Content-Length header to zero. DELETE Used for deleting resources.

http://developer.github.com/v3/#authentication

  • Basic, OAuth2 Token (header), OAuth2 Token (parameter), Oauth2 Key/Secret
  • Authenticating with invalid credentials will return 401 Unauthorized
  • After detecting several requests with invalid credentials within a short period, the API will temporarily reject all authentication attempts for that user (including ones with valid credentials) with 403 Forbidden:

http://developer.github.com/v3/#hypermedia http://developer.github.com/v3/#pagination

http://developer.github.com/v3/#rate-limiting

  • HTTP/1.1 302 Found
  • Provides info in X-headers

http://developer.github.com/v3/#cross-origin-resource-sharing

  • Any domain that is registered as an OAuth Application is accepted.
  • A really good example (almost perfect according to some blogs) example of a proper Hypermedia API.

HTTP Status (Response) codes

  • Spec: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html (Try and match to the spec as much as possible)
    • 10.1 Informational 1xx
    • 10.1.2 101 Switching Protocols: For example, switching to a newer version of HTTP is advantageous over older versions, and switching to a real-time, synchronous protocol might be advantageous when delivering resources that use such features.
    • 10.2 Successful 2xx
    • 10.2.1 200 OK
    • 10.2.2 201 Created: The request has been fulfilled and resulted in a new resource being created
    • 10.2.3 202 Accepted: The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon.
    • 10.2.5 204 No Content: The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation.
    • 10.2.6 205 Reset Content: The server has fulfilled the request and the user agent SHOULD reset the document view which caused the request to be sent. This response is primarily intended to allow input for actions to take place via user input, followed by a clearing of the form in which the input is given so that the user can easily initiate another input action.
    • 10.3 Redirection 3xx
    • 10.3.2 301 Moved Permanently
    • 10.3.3 302 Found (temporary redirect)
    • 10.3.5 304 Not Modified
    • 10.3.8 307 Temporary Redirect
    • 10.4 Client Error 4xx
    • 10.4.2 401 Unauthorized
    • 10.4.3 402 Payment Required
    • 10.4.4 403 Forbidden
    • 10.4.5 404 Not Found
    • 10.4.6 405 Method Not Allowed: The method (GET/etc) specified in the Request-Line is not allowed for the resource identified by the Request-URI. The response MUST include an Allow header containing a list of valid methods for the requested resource.
    • 10.5 Server Error 5xx
    • 10.5.1 500 Internal Server Error: The server encountered an unexpected condition which prevented it from fulfilling the request.
    • 10.5.2 501 Not Implemented: The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.
    • 503 Service Unavailable: The implication is that this is a temporary condition which will be alleviated after some delay. If known, the length of the delay MAY be indicated in a Retry-After header. If no Retry-After is given, the client SHOULD handle the response as it would for a 500 response.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment