Mockoon's APIs glossary

 Table of content

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

 A

 API (Application Programming Interface)

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.

See also: Web API, REST API

 Authentication

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

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.

 B

 Body

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

 C

 Cache

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.

 Client

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

 CORS (Cross-Origin Resouce Sharing)

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 (Create Read Update Delete)

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:

• POST /resource for an operation Creating a resource.
• GET /resource for an operation Reading a resource.
• PUT /resource for an operation Updating a resource.
• DELETE /resource for an operation Deleting a resource.

 E

 Endpoint

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.

 External API

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

 API Gateway

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.

 H

 Header

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.

 HTTP/HTTPS

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.

 I

 Internal API

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

 J

 JSON

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
}

 K

 API Key

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.

 L

 Latency

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

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.

 M

 Methods (HTTP methods)

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 resource
• GET: retrieve a resource
• PUT: update an existing resource
• DELETE: remove an existing resource

See also: CRUD

 Middleware

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.

 Mime type

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 format
• application/xml: XML format
• text/html: HTML format
• text/plain: Plain text format

 API Mocking

API 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.

 O

 OpenAPI/Swagger

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.

 P

 Pagination

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.