cloud of words, http, rest, cache, header

Mockoon's APIs glossary

This article provides a glossary for many terms and acronyms you will come accross when working with APIs

Table of content#

API (Application Programming Interface)
Body
Cache
Client
CORS (Cross-Origin Resouce Sharing)
CRUD (Create Read Update Delete)
Endpoint
External API
Header
Internal API
JSON
API Key
Methods (HTTP methods)
API Mocking
Path Parameters
Query Parameters
Request
Response
Resource
REST API
Route
Server
Status code (HTTP)
URL (Uniform Resource Locator)
Web API

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.
→ Learn more in our API guide

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

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.

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.

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.

→ Learn how to setup headers with Mockoon

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.

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
}

→ Learn how to generate fake JSON with Mockoon

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.

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

→ Learn more in our REST API guide

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.

→ Learn more in our API mocking guide

P#

Path Parameters#

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.

Q#

Query Parameters#

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.

R#

Request#

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.

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.

Resource#

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.

REST API#

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

Route#

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.

S#

Server#

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.

Status code (HTTP)#

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

U#

URL (Uniform Resource Locator)#

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:

The protocol used to reach the resource: HTTPS.
The hostname: company.com.
A path to the resource: /api/users.

W#

Web API#

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