REST API glossary
78 REST API terms, from Novice to Master. Start with the basics or jump to a level.
Updated
Novice
- API
- A set of rules that lets one program ask another for data or actions.
- Client and Server
- The client asks; the server answers.
- Endpoint
- One address an API offers: a method plus a path.
- HTTP
- The request-and-response language of the web.
- HTTPS
- HTTP over an encrypted connection.
- JSON
- The text format most APIs use for data.
- Request
- What the client sends: method, URL, headers and an optional body.
- Resource
- A thing an API lets you work with, identified by a URL.
- Response
- What the server sends back: a status code, headers and usually a body.
- REST
- An API style built around resources with URLs, used through standard HTTP methods.
- URL
- The full address of a resource on the web.
- Web API
- An API you call over HTTP, usually getting JSON back.
Apprentice
- 200 OK
- The request worked and the body holds the result.
- 201 Created
- A new resource was created.
- 204 No Content
- It worked and there is no body to return.
- 400 Bad Request
- The request is invalid, such as a missing or wrong field.
- 401 Unauthorized
- No valid credentials were sent: sign in first.
- 403 Forbidden
- Signed in, but not allowed to do this.
- 404 Not Found
- Nothing exists at that URL.
- 500 Internal Server Error
- Something broke on the server.
- Content-Type
- The header that says what format a body is in.
- curl for APIs
- A command-line tool for sending HTTP requests.
- DELETE (HTTP)
- The method that removes a resource.
- GET
- The method that reads data without changing anything.
- Header
- A name-value line of extra information on a request or response.
- HTTP Method
- The verb that says what a request wants to do.
- PATCH
- The method that updates only some fields of a resource.
- Path Parameter
- A variable part of the URL path, like an ID.
- POST
- The method that creates a new resource.
- Postman and Insomnia
- Desktop apps for building and sending API requests by hand.
- PUT
- The method that replaces a whole resource.
- Query String
- The ?key=value part of a URL, used for filters and paging.
- Request Body
- The data sent with a request, usually JSON.
- Status Code
- The three-digit result number: 2xx success, 4xx client error, 5xx server error.
Journeyman
- 409 Conflict
- The request clashes with the current state, like a duplicate.
- 422 Unprocessable Content
- Well-formed data whose values break the rules.
- 429 Too Many Requests
- You sent too many requests; wait and try again.
- API Key
- A secret string that identifies the calling program.
- API Versioning
- Letting an API change without breaking existing clients.
- Authentication
- Proving who you are.
- Authorization
- Deciding what an identified user is allowed to do.
- Bearer Token
- A token sent as "Authorization: Bearer ..."; whoever has it is treated as the user.
- Cookie
- Small data the browser stores and sends back to the same site on every request.
- CORS
- Server rules that tell browsers which other sites may call it.
- CRUD
- Create, Read, Update, Delete: the four basic data actions.
- Filtering and Sorting
- Query-string parameters that narrow and order a list.
- Idempotent Method
- A request with the same effect whether sent once or many times.
- JWT
- A signed token carrying who the user is and when it expires.
- Location Header
- A header pointing to a new resource or a redirect target.
- OpenAPI
- A standard machine-readable description of an API.
- Pagination
- Returning a large list in pages with a total count.
- Problem Details
- A standard JSON shape for API error responses.
- Resource Naming
- Name endpoints with plural nouns and IDs, letting the method be the verb.
- Safe Method
- A method that only reads and never changes data, like GET.
- Stateless
- Each request carries all it needs; the server remembers nothing in between.
- Swagger UI
- An interactive web page, built from OpenAPI, for trying an API.
Freelancer
- API Gateway
- A single front door that routes requests to many backend services.
- Backend for Frontend
- A small server built for one front end, shaping data and holding tokens.
- Caching Headers
- Headers that say how long a response may be reused.
- Conditional Request
- A request that only proceeds if the resource is still in the expected state.
- Content Negotiation
- The client asks for a format with Accept; the server picks one it supports.
- Contract Testing
- Checking an API still matches its agreed description.
- ETag
- A version fingerprint that lets clients skip downloading unchanged data.
- Idempotency Key
- A unique value that stops a retried POST from happening twice.
- Long-Running Operation
- Answering 202 at once and letting the client poll a status URL.
- OAuth 2.0
- A standard for granting apps limited access via tokens instead of passwords.
- OpenID Connect
- Sign-in built on OAuth 2.0; used by "Sign in with Google".
- Preflight Request
- The OPTIONS check a browser sends before some cross-origin requests.
- Rate Limiting
- Capping how many requests a client can send in a period.
- Refresh Token
- A long-lived token used to get new short-lived access tokens.
- Webhook
- An HTTP call a service sends to your URL when something happens.
Master
- API-First Design
- Agreeing on the API contract before writing the implementation.
- gRPC
- A fast, binary, contract-first API style often used between services.
- HATEOAS
- Responses include links to the next possible actions.
- HTTP/2 and HTTP/3
- Newer HTTP versions that send many requests at once over one connection.
- Mutual TLS
- Both client and server present certificates to prove who they are.
- Richardson Maturity Model
- A four-level scale of how fully an API uses REST ideas.
- Server-Sent Events
- A response kept open so the server can push a stream of events.