GITHUB API design cheatsheet

API Design Cheat Sheet

  1. Build the API with consumers in mind–as a product in its own right.
    • Not for a specific UI.
    • Embrace flexibility / tunability of each endpoint (see #5, 6 & 7).
    • Eat your own dogfood, even if you have to mockup an example UI.
  2. Use the Collection Metaphor.
    • Two URLs (endpoints) per resource:
      • The resource collection (e.g. /orders)
      • Individual resource within the collection (e.g. /orders/{orderId}).
    • Use plural forms (‘orders’ instead of ‘order’).
    • Alternate resource names with IDs as URL nodes (e.g. /orders/{orderId}/items/{itemId})
    • Keep URLs as short as possible. Preferably, no more-than three nodes per URL.
  3. Use nouns as resource names (e.g. don’t use verbs in URLs).
  4. Make resource representations meaningful.
    • “No Naked IDs!” No plain IDs embedded in responses. Use links and reference objects.
    • Design resource representations. Don’t simply represent database tables.
    • Merge representations. Don’t expose relationship tables as two IDs.
  5. Support filtering, sorting, and pagination on collections.
  6. Support link expansion of relationships. Allow clients to expand the data contained in the response by including additional representations instead of, or in addition to, links.
  7. Support field projections on resources. Allow clients to reduce the number of fields that come back in the response.
  8. Use the HTTP method names to mean something:
    • POST – create and other non-idempotent operations.
    • PUT – update.
    • GET – read a resource or collection.
    • DELETE – remove a resource or collection.
  9. Use HTTP status codes to be meaningful.
    • 200 – Success.
    • 201 – Created. Returned on successful creation of a new resource. Include a ‘Location’ header with a link to the newly-created resource.
    • 400 – Bad request. Data issues such as invalid JSON, etc.
    • 404 – Not found. Resource not found on GET.
    • 409 – Conflict. Duplicate data or invalid data state would occur.
  10. Use ISO 8601 timepoint formats for dates in representations.
  11. Consider connectedness by utilizing a linking strategy. Some popular examples are:
  12. Use OAuth2 to secure your API.
    • Use a Bearer token for authentication.
    • Require HTTPS / TLS / SSL to access your APIs. OAuth2 Bearer tokens demand it. Unencrypted communication over HTTP allows for simple eavesdroppping and impersonation.
  13. Use Content-Type negotiation to describe incoming request payloads.For example, let’s say you’re doing ratings, including a thumbs-up/thumbs-down and five-star rating. You have one route to create a rating: POST /ratingsHow do you distinguish the incoming data to the service so it can determine which rating type it is: thumbs-up or five star?

    The temptation is to create one route for each rating type: POST /ratings/five_star and POST /ratings/thumbs_up

    However, by using Content-Type negotiation we can use our same POST /ratings route for both types. By setting the Content-Type header on the request to something like Content-Type: application/vnd.company.rating.thumbsup or Content-Type: application/vnd.company.rating.fivestar the server can determine how to process the incoming rating data.

  14. Evolution over versioning. However, if versioning, use the Accept header instead of versioning in the URL.
    • Versioning via the URL signifies a ‘platform’ version and the entire platform must be versioned at the same time to enable the linking strategy.
    • Versioning via the Accept header is versioning the resource.
    • Additions to a JSON response do not require versioning. However, additions to a JSON request body that are ‘required’ are troublesome–and may require versioning.
    • Hypermedia linking and versioning is troublesome no matter what–minimize it.
    • Note that a version in the URL, while discouraged, can be used as a ‘platform’ version. It should appear as the first node in the path and not version individual endpoints differently (e.g. api.example.com/v1/…).
  15. Consider Cache-ability. At a minimum, use the following response headers:
    • ETag – An arbitrary string for the version of a representation. Make sure to include the media type in the hash value, because that makes a different representation. (ex: ETag: “686897696a7c876b7e”)
    • Date – Date and time the response was returned (in RFC1123 format). (ex: Date: Sun, 06 Nov 1994 08:49:37 GMT)
    • Cache-Control – The maximum number of seconds (max age) a response can be cached. However, if caching is not supported for the response, then no-cache is the value. (ex: Cache-Control: 360 or Cache-Control: no-cache)
    • Expires – If max age is given, contains the timestamp (in RFC1123 format) for when the response expires, which is the value of Date (e.g. now) plus max age. If caching is not supported for the response, this header is not present. (ex: Expires: Sun, 06 Nov 1994 08:49:37 GMT)
    • Pragma – When Cache-Control is ‘no-cache’ this header is also set to ‘no-cache’. Otherwise, it is not present. (ex: Pragma: no-cache)
    • Last-Modified – The timestamp that the resource itself was modified last (in RFC1123 format). (ex: Last-Modified: Sun, 06 Nov 1994 08:49:37 GMT)
  16. Ensure that your GET, PUT, and DELETE operations are all idempotent. There should be no adverse side affects from operations.

github Platform Building cheat sheet

See also: [API Design Cheat Sheet](https://github.com/RestCheatSheet/api-cheat-sheet#api-design-cheat-sheet)

# Platform-Building Cheat Sheet

First off, we need to understand what is meant by the term **’platform’** for the organization.
In todays world, the term ‘platform’ is such an overused buzzword that it is largely meaningless.
Platforms exist at many levels in the technology stack: hardware, datacenter, database,
messaging, etc. and can also be used to describe ecosystems of user experiences.

The view presented here is decidedly business focused: the ‘platform’ is really the method
of exposing and growing the digital business model and its offerings. So, the following ground rules
define the platform as the digital server-side, back-end data and functionality, leaving the user
experiences to be crafted (whether mobile, web or other) on top of that business functionality.

This API-centric definition of ‘platform’ enables:

* Rapid user experience revision
* Consistent user experience across devices
* Better channel adaptation
* Faster and cheaper third-party integrations
* Increased innovation capabilities.

## Platform Ground Rules

1. **Mobile** applications are a first-class citizen and consumer of the platform.
* Making mobile a priority increases ease of use and adoption for everyone.
1. The platform exposes its data and functionality via a complete set of **RESTful APIs**.
* An API-based strategy maximizes reuse and flexibility.
1. All service interfaces and events are designed from the ground up to be **public facing**.
* Causes design for ease of use, flexibility and reuse.
1. Each team of developers access all APIs using their team’s own **registered developer key**.
* Improves security, auditability.
1. There is a **single token source** and format for all APIs.
* Assists in ease of use and ensures all functionality is available to consumers.
1. The platform will notify interested observers of all resource state changes via **fully-composed events**.
* Enables synchronization asynchronously (for all create, update, delete state changes).
1. All APIs use a **single identity** to represent the consumer / user.
* Enables analytics and reasoning about consumers.
1. All APIs have a **consistent look and feel**, and are documented at a single, publicly-available location.
* Maximizes reuse and ease of use.
1. No private interfaces. **No backdoors**. No shared databases across teams (Observe ‘Bounded Contexts’).
* Ensures the public interfaces are sound.
1. APIs are deployed in a **distributed, always-on** architecture (multi-node, multi-zone, and multi-region) with a discipline towards resilience.
* Horizontal scale on commodity hardware, global reach. Account for the inevitable failures.