Anatomy of an API

Anatomy of an API

Hacking APIs


3 min read

Provider: Host of an API.

Consumer: Person/Entity making the request.

API Gateway: API management component that acts as an entry point to a web application. The gateway distributes the request to whichever microservice is needed. Can handle security controls such as authentication, authorization, load balancing, rate limiting.

Microservice: Modular piece that handles a specific function.

CRUD: Create, Read, Update, Delete


Representational State Transfer (REST): set of architectural constraints for applications that communicate using HTTP methods. The following constraints are suggestions instead of strict guidelines:

  1. Uniform interface: Client device should not matter (mobile, laptop, 105, etc)

  2. Client/server architecture

  3. Stateless: Do not maintain the state during communications. Tokens are used to provide a State-like experience.

  4. Cacheable: Requests are cached to improve the performance and scalability

  5. Layered: diet should not have to know about the underlying server architecture

  6. Code on demand: Allows code to be sent to the client for execution.

Common RESTFUL Headers:

AUTHORIZATION: Pass token or credentials to API provider

CONTENT TYPE: Indicate the type of media being transferred

MIDDLEWARE (X): X-<anything> headers are known as middleware headers and are used for different things eg X-Response-Time, X-API-Key, K-Rate-Limit


Specification that allows clients to define the structure of the data they want to request from the server. It is RESTFUL and query-centric. Allows users to retrieve specific data from the server using POST Requests, but still uses CRUD. It uses three operations with the post request:

  1. Query: operation to read/retrieve data.

  2. Mutation: submit and write data (includes delete).

  3. Subscription: read data when an event happens (used for live updates from a server).

GraphQL makes use of schemes which are collections of data that can be queried. This is equivalent to a POSTMAN collection for a REST API.


Frameworks used to help design APIs and automatically create human-readable documentation. The most common specifications include Open API Specification 3.1 aka Swagger and Restful API Modeling Language (RAML).

  1. JSON: Most widely used interchange format. Objects are represented as key-value pairs separated by commas.

  2. XML: Mostly associated with SOAP APIs that use POST requests over HTTP

  3. YAML: Contains my value pairs where the value may be any of the YAML data types


Authentication: the process of proving and verifying an identity.

BASIC Auth - Username and password are provided in the request header or body. APIs are stateless so it is common that the first request authenticates the user then the subsequent requests use an API key or something similar.

API Key - Unique strings used to grant access to approved consumers. It is typically required in query parameters, request headers, body data, or as a cookie. Usually have expiration dates to prevent security issues that may cause long-term effects if the key is ever leaked.

JWT - Generated by providers and sent to consumers after having authenticated with a username and password to mimic statefulness. Consists of:

Header algorithm used for signing

Payload data included in token such as username

Signature encoded and encrypted message used to validate the token

HMAC (Hash-based message authentication code)

The provider creates a key and shares it with the consumer. HMAC hash function is applied to consumer request data and secret key. The resulting hash is added to the consumer request and sent to the provider. Provider calculates AMAC and compares the output to the value provided by the consumer. If it does not match, the message is likely to have been tampered with.

OAuth 2.0

Allows different services to access each other's data, often using APIs to facilitate service-to-service communications. The user grants an application access to a service (authorization server), the service creates a token, and then the application uses the token to exchange data with the service (also the resource server).