04. HTTP Servers, REST and GraphQL

Databases, JS behavior, REST versioning

REST

A REST service is a platform and language independent service that runs on top of HTTP(S).

REST services use the same HTTP verbs used by web browsers and hence, they can be thought of as a subset of web apps.

HTTP/REST resources usually have a unique identifier (e.g. integer. UUID). Often, the structure of the URL mirrors the structure of the data.

Misc:

• PUT is a replace operation; PATCH is a partial change
  • How would you represent the deletion of a property? Null value?
• REST has no security, encryption, session management or QoS guarantees
• REST, being built on top of HTTP, is stateless
  • The entire resource is returned
  • Underfetching/overfetching due to request-response architecture

URLs:

• Hide all implementation details
  • e.g. file extensions related to the server software (php) so that server language can change
• Be consistent with singularity/plurality of resource names
• Keep everything lowercase
• Replace spaces for hyphens
• Always provide default page/resource as a response

State timescales (shortest to longest):

• Individual HTTP request: stateless
• Business transaction: e.g. multiple GET requests to get information, then POST request
• Session state: required for web applications
• Preferences: state stored in DB
• Record state

Session state:

• Include session ID as query parameter in GET requests: easy to see and copy
• Cookies: random identifier sent with each HTTP request to the server
  • Session/persistent: deleted/stored when browser closed/session ended
  • Secure: HTTPS only
  • HTTPOnly: not accessible via JS
  • Set-cookie: key=value; Expires = date
  • Cookies identify the combination of user account/browser/device

HTTP

Stateless protocol; each request/response self-contained.

• GET: retrieve named resource
• HEAD: GET, but return only headers
• POST: create new resource
• PUT: change specified resource
• OPTIONS: get supported methods for the given resource
• PATCH: modify existing resource
• DELETE: delete specified resource

Safe methods (nullipotentcy): methods that do not modify resources. GET and HEAD are safe.

Idempotent methods: intended state is the same regardless of how many times the method is called. POST and PATCH are not idempotent.

The lack of side effects helps in making the API more fault tolerant

CAP Theorem

• Consistency: read will always return most recent write
• Availability: non-failing node will return reasonable response within a reasonable amount of time
• Partition tolerance: system will continue to function when it becomes fragmented

In theory, you can have two of the three. However, networks fail (which you have no control over) so you must tolerate partitioning.

API Versioning

Ensure compatibility between the API provider and users. Adding new features may not require new versions, but removing or amending features will require a new version.

Versions may be useful for:

• A/B testing
• System testing; dev, test, prod
• For different subsets of clients e.g. business vs consumers, geographical/political regions
• Rollback of unacceptable APIs

From a client perspective, an API is backwards compatible if it it can continue to function through a service change (e.g. adding new features) and forwards compatible if the client can be changed without needing a service change.

Semantic Versioning

MAJOR.MINOR.PATCH:

• Major: incompatible API changes
• Minor: functionality added in backwards-compatible manner
• Patch: bug fixes

Encoding Versioning

• Query parameter (e.g. ?version=xx.xx)
• URL (e.g. api/v1)
  • Semantically messy: looks like you are selecting version of a resource
• Header
  • Hard to test

Publishing

• Credibility: trust that the API will do what it says on the tin
• Support: support the API
• Success: sharing success stories
• Access: no SDK is the best SDK (e.g. cURL requests)
• Documentation should be current, accurate and hopefully have guides/tutorials
• SDKs/samples in preferred languages
• Free/freemium use
• Instant API keys
• Sandboxes