This article provides a glossary for many terms and acronyms you will come accross when working with APIs
API (Application Programming Interface)
Authentication
Authorization
Body
Cache
Client
CORS (Cross-Origin Resouce Sharing)
CRUD (Create Read Update Delete)
Endpoint
External API
API Gateway
Header
HTTP/HTTPS
Internal API
JSON
API Key
Latency
Load balancing
Methods (HTTP methods)
Middleware
Mime type
API Mocking
OpenAPI/Swagger
Pagination
Path Parameters
Payload
Polling
Query Parameters
Rate limiting
Request
Response
Resource
REST API
Route
Server
Status code (HTTP)
URL (Uniform Resource Locator)
Versioning
Web API
Webhooks
WebSocket
API is the acronym for Application Programming Interface. In contrast to a User Interface (UI) that connects a person to a computer, it's a software-to-software interface, or intermediary, enabling two applications to talk to each other.
📘 Learn more in our API guide
Authentication is the process of verifying the identity of a user or system. In the context of APIs, it often involves the use of API keys, tokens, or other credentials to ensure that only authorized clients can access the API. An API may require authentication to protect sensitive data or resources and to ensure that only legitimate users can perform actions on the API.
It is usually done by sending credentials in the request headers, like the Authorization
header, or in the body of the request. An invalid or missing authentication will usually result in a 401 Unauthorized
status code.
Authorization is the process of determining whether a user or system has permission to perform a specific action or access certain resources. In APIs, this often follows authentication and involves checking the user's permissions against the requested resource or action. For example, an API may allow a user to read data but not modify it, or it may restrict access to certain endpoints based on the user's role or permissions. Authorization is typically enforced by the API server and can be implemented using various methods, such as role-based access control (RBAC) or attribute-based access control (ABAC).
Missing access rights on a resource will usually result in a 403 Forbidden
status code.
The body refers to the data transmitted in an API transaction in the request or the response. Requests and responses do not always contain a body. JSON is one of the most popular data formats to transfer data in the body
See also: Payload
In an API, a cache is a system for storing and retrieving responses to avoid reprocessing requests that are frequent and identical. Multiple cache systems may coexist at different levels: clients (browsers), API gateways or proxies, servers, etc. Servers usually indicate to the client the caching policy of a request using headers.
A client is a piece of hardware or software that access services or resources made available by servers in a client-server model. It usually sends a request to the server, which processes it and returns a response. The client may access the server using a network, especially when the server is not on the same computer system.
For example, a web browser is a client that connects to web servers to display web pages.
See also: Server
Cross-Origin Resource Sharing is an HTTP mechanism that allows a server to indicate the origins from which a browser is allowed to load resources.
By default, cross-origin requests (originating from a different host than the one serving the API) are restricted, and only same-origin requests are allowed. Practically, for all non-simple requests (based on multiple criteria, like the HTTP method used, the presence of a JSON body, etc.), browsers send a pre-flight request using the OPTIONS
HTTP method and read the response's headers (Access-Control-Allow-Origin
, Access-Control-Allow-Methods
, Access-Control-Allow-Headers
, etc.) to check if the server allows requests emanating from this specific host.
CRUD is an acronym for Create, Read, Update, and Delete, four basic operations of persistent storages. It is usually used in the REST API world to describe a group of resource endpoints and HTTP methods matching each of the operations:
An endpoint is a communication channel or a location where an API will receive requests for a specific resource. For example, in a REST API, accessing or modifying information related to users or invoices would be available on multiple /users
or /invoices
routes.
An external API usually exposes a company's internal resources outside of the organization letting third-party companies and developers use the data, for example, to create new applications. They are usually subject to restrictions and may require a paid subscription.
See also: Internal API
An API Gateway is a server that acts as an intermediary between clients and backend services. It is responsible for routing requests from clients to the appropriate services, handling tasks such as authentication, rate limiting, and caching. API Gateways can simplify the client-side experience by providing a single entry point for multiple services and can also enhance security by hiding the internal architecture of the API.
HTTP headers are used to pass additional information with HTTP requests and responses. They take the form of a list of key-value pairs.
Among the most used request headers:
Authorization: Bearer xxxxxxx
: contains the API key or token used to authenticate and identify the client.Content-Type: application/json
: indicates the mime type of the data sent in the request's body (application/json
, text/html
, etc.).Accept-Encoding: gzip, deflate, br
: indicates the types of data encoding supported by the client.Some widely used response headers:
Content-Type: application/json
: indicates the mime type of the data sent in the response's body (application/json
, text/html
, etc.).Cache-Control: max-age=604800
: to indicate the duration after which the response should be refreshed.Last-Modified: Fri, 24 June 2022 08:00:00 GMT
: indicate the data when the resource was last modified.💡 Learn how to setup headers with Mockoon
HTTP (Hypertext Transfer Protocol) is the foundation of data communication on the web. It is an application layer protocol used for transmitting hypermedia documents, such as HTML. HTTPS (HTTP Secure) is the secure version of HTTP, which uses encryption (SSL/TLS) to protect the data exchanged between clients and servers.
An internal API provides resources within an organization's software system. They are usually consumed by internal applications and back-ends and are often used in micro-services architectures. Internal APIs target in-house services and developers and are an efficient way to share departments' data within the organization.
See also: External API
JSON is a data format using human-readable text to transmit data objects consisting of key-value pairs. It is a popular data format for web APIs used in the bodies of requests and responses of API transactions.
A JSON example:
Copy{ "response": "success", "status": 200 }
💡 Learn how to generate fake JSON with Mockoon
An API key is a unique identifier used to authenticate and identify a user or an application accessing an API. Most APIs require their consumers (companies, developers, etc.) to register and request an API key as they are often paid products subjected to restrictions: consumer identification, volume billing, etc.
API keys are frequently sent by the client along with the request in an Authorization
header.
Latency is the time it takes for a request to travel from the client to the server and back, including the time taken by the server to process the request and generate a response. It is usually measured in milliseconds (ms) and can be affected by various factors, such as network speed, server load, and the complexity of the request.
Load balancing is the process of distributing incoming API requests across multiple servers or instances to ensure that no single server becomes overwhelmed with traffic. It helps improve the performance, reliability, and scalability of an API by preventing bottlenecks and ensuring that resources are used efficiently. Load balancers can be implemented at various levels, including hardware, software, or cloud-based solutions.
A request is always targeting an API route which comprises an HTTP verb or method, and a path. It indicates to the server what action the client intends to perform on a specific resource. There are multiple methods available: GET
, HEAD
, POST
, PUT
, DELETE
, CONNECT
, OPTIONS
, TRACE
, PATCH
.
The most used ones are the following and embody specific meanings in REST APIs:
POST
: create a new resourceGET
: retrieve a resourcePUT
: update an existing resourceDELETE
: remove an existing resource📘 Learn more in our REST API guide
📃 Check out complete list of HTTP methods.
See also: CRUD
Middleware refers to software components that sit between the client and server in an API architecture. They can intercept and process requests and responses, allowing for tasks such as logging, authentication, and data transformation. Middleware can be used to add additional functionality to an API without modifying the core logic of the application.
A MIME type (Multipurpose Internet Mail Extensions type) is a standard way to indicate the nature and format of a document, file, or byte stream. In the context of APIs, MIME types are used to specify the format of the data being sent in requests and responses, and is usually included in the Content-Type
header of the request or response. It helps the client and server understand how to interpret the data being exchanged. Common MIME types include:
application/json
: JSON formatapplication/xml
: XML formattext/html
: HTML formattext/plain
: Plain text formatAPI mocking is the action of simulating or imitating actual APIs by answering fake realistic responses to requests. It replaces APIs you cannot currently use because they are unavailable, down, or still under development. APIs could also be unavailable due to the context: like a restricted testing environment. It is a fast and easy way to test your applications with the APIs you are integrating, without the hassles.
📘 Learn more in our API mocking guide
OpenAPI (formerly known as Swagger) is a specification for building APIs. It provides a standard way to describe the structure and behavior of an API using a JSON or YAML document. This document serves as a contract between the API provider and the consumers, allowing for better collaboration, documentation, and automation.
Pagination is a technique used in APIs to divide large sets of data into smaller, manageable chunks or pages. It allows clients to retrieve data in smaller portions rather than fetching all the data at once, which can improve performance and reduce the load on the server. Pagination is often implemented using query parameters, such as page
and limit
, to specify which page of data to retrieve and how many items per page.
A path parameter is a non-optional section of the route's path used as a placeholder populated with a value during a request. It allows the client to indicate the target of the request to the server. They are usually represented in API documentations between curly braces or preceded by a colon.
For example, in /users/{id}
or /users/:id
, id
is a path parameter indicating that the action targets a user with a specific id: /users/123
. It is up to the API server to define which query parameters are available and needed.
See also: Query parameters
The payload is the data sent by the client in a request or returned by the server in a response. In the context of APIs, the payload typically contains the information needed to create, update, or retrieve a resource. The format of the payload can vary depending on the API and the specific endpoint being used. Common formats include JSON, XML, and form data.
See also: Body
Polling is a technique used in APIs to retrieve data from the server at regular intervals. Instead of waiting for the server to push updates to the client (as with webhooks), the client repeatedly sends requests to the server to check for new data. This can be useful in scenarios where real-time updates are not critical, but it can also lead to increased server load and latency.
A query parameter is an optional parameter added by a client, placed after the route's path, and sent with the request. It allows the client to add more parameters to its request. They are separated from the path by an interrogation mark and represented as key-value pairs separated by ampersands. For example, in /users?filter=active&sort=asc
, two query parameters are sent: a filter
parameter set to active
, and a sort
parameter set to asc
. It is up to the API server to define which query parameters are available and needed.
See also: Path parameters
Rate limiting is a technique used in APIs to control the amount of incoming requests from clients within a specific time frame, for example, allowing a maximum of 100 requests per minute per client. It helps prevent abuse, ensures fair usage, and protects the server from being overwhelmed by too many requests. When a client exceeds the allowed request limit, the server typically responds with a 429 Too Many Requests
status code.
A request is usually sent by a client connecting to an API server which will process it and send a response back to the client.
See also: Response
A response is built by a server after processing a request sent by the client. It usually contains the data requested by the client and information related to the execution of the request, like the status code.
See also: Request
In REST APIs, a resource is an object with a type, associated data, and optional sub-resources. They are usually interacted with individually or in collections through endpoints. For example, an object of type User
, which can be read individually on the GET /users/{id}
endpoint.
See also: CRUD
REST stands for REpresentational State Transfer. It's a software architectural style that defines a set of constraints used to create standardized APIs. Web APIs adhering to the REST architectural constraints are called RESTful APIs. RESTful APIs must follow six constraints: client-server architecture, statelessness, cacheability, layered system, code on demand, and uniform interface.
📘 Learn more in our REST API guide
In REST APIs, routes are couples of HTTP methods and paths of an API, usually representing a action to be performed on a specific resource. For example, accessing information about the users or invoices would be done on routes named after the resources using the GET
method: GET company.com/api/users
or GET company.com/api/invoices
.
See also: CRUD
A server is a piece of hardware or software providing functionalities to other programs or devices called clients. In a client-server architecture, servers can provide different functionalities or services, such as providing resources or content.
Client-server systems usually implement a request-response model where the client sends a request to the server, and the server returns a response to the client after performing a server-side action.
See also: Client
An HTTP status code is added to the response by the server to indicate to the client the status of its request without having to further analyze the other response's components (headers, body, etc.). The status code varies depending on the success of the action but also on its nature. More concretely, it's a number with three digits (between 100 and 599) associated with a name: 200 Success
, 404 Not Found
, etc. There are many status codes grouped into five main categories: informational responses (1xx), successes (2xx), redirections (3xx), client errors (4xx), and server errors (5xx).
📘 Learn more in our API guide
A URL is a reference to a web resource specifying its location on a network and a mechanism to retrieve this resource. A typical URL, like https://company.com/api/users
, contains multiple information:
HTTPS
.company.com
./api/users
.Versioning is the process of assigning unique version numbers to different iterations of an API. It allows developers to make changes, add features, or fix bugs without disrupting existing clients that rely on a specific version of the API. Common versioning strategies include:
/api/v1/users
).Accept: application/vnd.company.v1+json
)./api/users?version=1
).Web APIs are a specific type of APIs that can be accessed over the web, frequently using the HTTP protocol. They usually involve a client (your browser) and a server exposing resources publicly.
📘 Learn more in our API guide
See also: REST API
Webhooks are a way for an API to send real-time notifications or data to a client when certain events occur. Instead of the client polling the API for updates, the API sends a request to a predefined URL (the webhook endpoint) when an event happens. This allows for more efficient communication and reduces the need for constant polling.
WebSocket is a protocol that enables full-duplex communication channels over a single TCP connection. It allows for real-time data exchange between a client and a server, making it suitable for applications that require low latency and high interactivity, such as chat applications, online gaming, and live data feeds. WebSockets are often used in conjunction with APIs to provide real-time updates and notifications.