REST API Cheatsheet

Source: https://www.youtube.com/watch?v=5WXYw4J4QOU

POST, GET, PUT, DELETE != CRUD
no verbs -> just nouns for Resources: /applications or /applications/123
Possible Responses: Collection of Resources (e.g. with Links) or One instance of a Resource
Keep your API course grained to be scaleble to future requirements
For Resources: Be as specific as possible: /customers vs. /newsletter-customers and /registered-customers
PUT for Create: Can be used when the Client has the ability to create an identifier for the Resource himself. But it has to contain a full replacement of the dataset: PUT /applications/123
PUT for Update: Has to contain the a full replacement of the dataset (Full Update Operation): The reason why is that PUT has to be Idempotent (??? Does this make sense ???)
POST for Create: The request goes to a parent resource like: POST /applications The response has to be 201 Created and have a header with Location of the just created resource: https://api.myapp.com/applications/123
POST for Update: Only change one property of the resource (Partial Update): Reponse should be 200 OK. POST is not idempotent. You can't call it multiple times and expect the resource to be identical after eaach request
Media-Types: For format specification and parsing rules of the response body for the client. For Request: Accept-Header (Client tells the server what format it wants). For Response: Content-Type-Header (Contains the MIME-Type of the body being sent: e.g. application/json or custom MIME-Types like application/foo+json (the body is structured to the foo media type specification) or application/foo+json;application (add addons/fragments to express not only the format but also the resource inside of it: This is a foo JSON document that happens to be an application Ressource)
Base-URL: https://api.foo.com (simpler -> better as customers (developers) want the easiest path to adoption) vs. https://www.foo.com/dev/service/api/rest
Versioning: URL https://api.foo.com/v1 (simpler -> pragmatic approach) vs. Media-Type application/json+foo;application,v=1 (URL doesn't change but it's hard for client developers to implement / understand it)
Resource Formats:
- Use camelCase notation for properties
- Date/Time/Timestamp: There is a standard: Use it: ISO 8601: { "createdTimestamp": "2017-11-15Tt18:10:24.343Z" } and use UTC!
- HREF: Every Resource contains its own unique link in the response body: { "href": "https://api.foo.com/v1/accounts/123" }
- Response Body: GET should return a response body always (Captain Obvious). POST should contain it when its feasable to have the most recent version of that object which might be slightly different than the request object: Return it by default and the client always gets the newest version of that object (or as an alternative: give the power to the client with: ?\_body=false to let him decide whether or not he wants the object back)
Content Negotiation: Get the content that you want as a client: Accept-Header: Accept: application/json, text/plain vs. Resource Extension: Like /applications/123.json or applications/123.csv (it conventionally overrides the Accept-Header
Resource References (Linking):
- Instance Reference: GET /accounts/123 { "href": "https://api.foo.com/v1/accounts/123", "name": "Tony", ... }
- Collection Reference: GET /accounts/123 { "href": "https://api.foo.com/v1/accounts/123", "name": "Tony", ..., "directory": { "href": "https://api.foo.com/v1/directories/345" } }
Reference Expansion (aka Entity Expansion or Link Expansion): GET /accounts/123?expand=directory { "href": "https://api.foo.com/v1/accounts/123", "name": "Tony", ..., "directory": { "href": "https://api.foo.com/v1/directories/345", "name": "Avengers", ... } } For Caching: Query-Parameters are taking into account for caching rules, so this is being cached under this specific URL
Partial Representations: GET /accounts/123?fields=name,surname,directory(name)

Pagination: Collection Resource supports querystring params: Offset, Limit: /applications?offset=50&limit=25

Example: GET /accounts

{
	"href": "https://api.foo.com/v1/accounts",
  "offset": 0,
  "limit": 25,
  "first": { "href": "https://api.foo.com/v1/accounts?offset=0" },
  "previous": null,
  "next": { "href": "https://api.foo.com/v1/accounts?offset=25" },
  "last": { "href": "..." },
  "items": [
  	{ "href": "https://api.foo.com/v1/accounts/1" },
      { "href": "https://api.foo.com/v1/accounts/2" },
      { "href": "https://api.foo.com/v1/accounts/3" },
      ...
  ]
}

Many to Many: Each n:m Mapping is a Resource: e.g. Group to Account: A Group contains Accounts and an Account contains Groups: The Ressource would be GroupMembership:

Example: GET /groupMemberships/678

{
  "href": "https://api.foo.com/groupMemberships/678",
  "account": { "href": "https://api.foo.com/accounts/123" },
  "group": { "href": "https://api.foo.com/groups/234" },
  ...
}

Another Example with the Ressource "Account": It contains the groups directly as well as the groupMemberships: GET /accounts/134

{
	"href": "https://api.foo.com/account/123",
  "name": "Tony",
  ...,
  "groups": [{ "href": "https://api.foo.com/groups/234" }],
  "groupMemberships": { "href": "https://api.foo.com/groupMemberships?accountId=123" }
}

Errors: Contain as much Information as possible (Developers are your customers)

Example: POST /directories -> 409 Conflict

{
	"status": 409,
  "code": 40924,
  "property": "name",
  "message": "A directory named 'Avengers' already exists.",
  "developerMessage": "A directory named 'Avengers' already exists. If you have a stale local cache, please expire it now.",
  "moreInfo": "https://www.foo.com/docs/api/errors/40924"
}

IDs: Should be globally unique. Avoid sequential numbers (possible security risk). Good candidates: UUIDs or Url64
HTTP Method Overrides: If clients doesn't support anything other than GET or POST: POST /accounts/123?_method=DELETE
Caching & Concurreny Control: ETag == Version Number for a specific Ressource:
- Example:
- Server (initial response): ETag: "2344afa23432"
- Client (later request): If-None-Match: "2344afa23432"
- Server (later response): 304 Not Modified
Security: Avoid sessions when possible (stateless scales better). Authorize based on Ressource content, and not on URLs (they can change). Use an existing protocol like OAuth2, Basic Auth over SSL
Maintenance: Use HTTP Redirects (e.g. for moving Ressources -> migrate URLs or deprecate them). Create abstraction layers in your code to minimize change in the API. Use well defined custom Media-Types (If you can do it: It is most resilient to changes over time).

ngnam/rest-api-cheatsheet.md

REST API Cheatsheet

ngnam commented Nov 27, 2021