API Vocabulary: 30 Terms Every Backend Developer Must Know

APIs are the language through which modern software speaks to itself. As a backend developer, you design them, document them, and spend hours in meetings talking about them. But do you know the precise English vocabulary to do all three confidently?

Knowing that a request “hits an endpoint” is not the same as being able to explain what idempotency means, why a 429 is different from a 503, or when to say “deprecate” versus “sunset” in a client-facing email.

These are the 30 terms that come up constantly in API design, code review, and stakeholder communication.

Part 1: Core API Concepts

1. API (Application Programming Interface) A defined contract that lets one piece of software communicate with another. When you build an API, you’re defining what requests are valid and what responses will be returned.

“We expose a public API so third parties can integrate with our platform without accessing our database directly.”

2. Endpoint A specific URL that your API exposes to perform a particular operation. Each endpoint represents a resource or action.

“The /users/{id}/orders endpoint returns all orders for a given user.”

3. Request A message sent by a client to the API asking it to do something — retrieve data, create a record, trigger an action.

“The client sends a POST request to /checkout with the cart contents in the body.”

4. Response What the API sends back after processing the request — typically including a status code and a body with data or an error message.

“The API responds with a 200 OK and a JSON object containing the user profile.”

5. Payload The actual data content of a request or response body — not the headers or metadata, just the data itself.

“The request payload includes the user’s email, name, and hashed password.”

6. Header Metadata attached to a request or response. Headers carry information like content type, authentication tokens, caching instructions, and rate limit details.

“The Authorization header must include a valid Bearer token for all authenticated endpoints.”

7. HTTP Methods (Verbs) The action types in REST APIs:

Method	Common use
`GET`	Retrieve a resource — read-only, no side effects
`POST`	Create a new resource
`PUT`	Replace an existing resource entirely
`PATCH`	Update part of an existing resource
`DELETE`	Remove a resource

“We use PATCH instead of PUT because we’re only updating the user’s email — not replacing the entire record.”

Part 2: HTTP Status Codes

Status codes tell you what happened. Knowing the vocabulary makes logs and error messages instantly readable.

8. 2xx — Success The request was received, understood, and processed successfully.

200 OK — standard success
201 Created — a new resource was created (used after successful POST)
204 No Content — success, but no body to return (common after DELETE)

“After the user creates a new project, the API returns 201 Created with the project ID in the Location header.”

9. 3xx — Redirection The client needs to take additional action — usually follow a redirect.

301 Moved Permanently — the resource has a new permanent URL
302 Found — temporary redirect
304 Not Modified — cached version is still valid (used with ETags)

10. 4xx — Client Errors The problem is on the client side — bad request, missing auth, wrong resource.

400 Bad Request — malformed request, missing required fields
401 Unauthorized — authentication required or token invalid
403 Forbidden — authenticated, but not permitted to access this resource
404 Not Found — the resource doesn’t exist
409 Conflict — the request conflicts with current state (e.g., duplicate email)
422 Unprocessable Entity — syntactically valid but semantically wrong (common in validation errors)
429 Too Many Requests — rate limit exceeded

“If the token is expired, we return 401. If the user is authenticated but doesn’t have permission, we return 403.”

11. 5xx — Server Errors Something went wrong on the server.

500 Internal Server Error — generic, unexpected error
502 Bad Gateway — upstream service returned an invalid response
503 Service Unavailable — server is down or overloaded — often temporary
504 Gateway Timeout — upstream service didn’t respond in time

“The 503 during the deploy was expected — we had the load balancer health checks failing while the new containers were warming up.”

Part 3: REST & API Design Vocabulary

12. REST (Representational State Transfer) An architectural style for building APIs using HTTP. RESTful APIs are stateless, resource-based, and use standard HTTP methods.

“Our public API is RESTful — each endpoint represents a resource, and we use standard HTTP verbs for operations.”

13. Resource A noun — the thing your API manages. In REST, endpoints are organized around resources.

“The main resources in our API are: users, orders, products, and payments.”

14. JSON (JavaScript Object Notation) The standard data format for most modern REST APIs — lightweight, human-readable, widely supported.

“All our endpoints accept and return JSON. Set Content-Type: application/json in your request headers.”

15. Query Parameter A key-value pair appended to a URL after ? to filter, sort, or paginate results.

“Use ?status=active&page=2&limit=20 to get the second page of active users.”

16. Path Parameter A variable embedded in the URL path to identify a specific resource.

“In /orders/{orderId}, orderId is a path parameter — it identifies which order you’re operating on.”

17. Pagination Breaking large collections of results into pages to avoid returning everything at once.

“The API uses cursor-based pagination — each response includes a next_cursor value for the next page.”

18. Rate Limiting Restricting how many requests a client can make in a given time window to protect the server.

“The public API is rate-limited to 100 requests per minute per API key. Exceeded limits return 429 Too Many Requests.”

19. Versioning Maintaining multiple versions of an API so existing clients aren’t broken when you make changes.

“We version via the URL path — /v1/users and /v2/users coexist. New clients should use v2.”

Part 4: Authentication & Security

20. Authentication (AuthN) Verifying who the caller is — proving identity.

“Authentication is handled via JWT tokens. Include the token in the Authorization: Bearer <token> header.”

21. Authorization (AuthZ) Deciding what the authenticated caller is allowed to do.

“Authorization is role-based. Editors can update posts, but only Admins can delete them.”

22. API Key A static secret token used to identify and authenticate a client application.

“Include your API key in the X-API-Key header for all requests.”

23. Bearer Token An access token (often a JWT) included in the Authorization header to prove the caller’s identity.

“Once authenticated, store the Bearer token securely — it grants access to all endpoints the user has permission for.”

24. OAuth 2.0 An authorization framework that allows a user to grant an application access to their data without sharing their password.

“We use OAuth 2.0 for third-party integrations — users authorize the app to access their account scopes without giving out their credentials.”

Part 5: Advanced API Concepts

25. Idempotency An operation is idempotent if calling it multiple times produces the same result as calling it once. GET, PUT, and DELETE are idempotent; POST is not.

“Payment processing endpoints are idempotent — include an Idempotency-Key header to prevent duplicate charges if the client retries on timeout.”

26. Stateless Each API request contains all the information needed to process it — the server doesn’t store session state between requests.

“REST APIs are stateless by design. Each request must include the auth token; the server doesn’t remember the previous call.”

27. Webhook A mechanism where your server pushes data to a client URL when an event occurs — the reverse of a standard request.

“Instead of polling for payment status, subscribe to our webhook. We’ll POST to your endpoint immediately when a payment completes.”

28. Deprecation / Sunset When an API endpoint or version is deprecated, it still works but is scheduled for removal. When it’s sunset, it’s been removed.

“The /v1/search endpoint is deprecated as of March 2026 and will be sunset on 1 September 2026. Please migrate to /v2/search.”

29. SLA (Service Level Agreement) A formal contract defining the expected availability and performance of the API.

“Our API SLA guarantees 99.9% uptime and a maximum response time of 500ms at the 95th percentile.”

30. Contract / API Contract The formal specification defining what requests are valid and what responses are guaranteed — often an OpenAPI/Swagger document.

“Before any integration work starts, get the API contract from the platform team. It defines every field, type, and error code.”

Quick Reference

Term	One-line definition
Endpoint	A specific URL for a specific operation
Payload	The data content of a request or response body
Idempotent	Same result whether called once or many times
Rate limiting	Max requests allowed per time window
Deprecation	Still works, but scheduled for removal
Webhook	Server pushes data to you when an event happens
AuthN	Who are you? (authentication)
AuthZ	What can you do? (authorization)
Stateless	Each request is self-contained, no session state
SLA	Guaranteed uptime and performance levels

Using These Terms in Communication

Knowing the terms isn’t enough — you need to use them correctly in conversations and documentation.

In a code review:

“This endpoint isn’t idempotent — if the client retries on a network timeout, we could create duplicate records. Add an Idempotency-Key header.”

In a planning meeting:

“We should version this change. If we modify the response schema without bumping the version, we’ll break existing integrations.”

In an incident post-mortem:

“The 503 cascade was triggered when the upstream payment API exceeded our timeout and started returning 504 responses to all authenticated requests.”

In client documentation:

“The /v1/reports endpoint is deprecated. It will be sunset on 30 June 2026. Please migrate to /v2/reports, which supports all the same parameters plus improved filtering.”