API glossary

AJAX

AJAX, which stands for "Asynchronous JavaScript And XML," is a technique for creating dynamic and interactive web pages. AJAX uses JavaScript to make requests to a web server in the background and retrieve data in various formats, including XML, HTML, or JSON. This data can be used to update specific parts of a web page without refreshing, which creates a more responsive and user-friendly experience.

API definition

An API definition is a human- and machine-readable document that describes the structure and behavior of an API, including its available endpoints, methods, parameters, data formats, and expected responses. API definitions can be written in various formats, such as OpenAPI (formerly known as Swagger), RAML (RESTful API Modeling Language), or API Blueprint.

API definitions play an essential role in the API design process, as they enable teams to align on the API's capabilities, use cases, and requirements. API definitions also provide the foundation for effective API documentation, which can help API producers attract new consumers and promote their APIs in the developer community.

Additional resources:

• RAML and API Blueprint: where are they now?
• Editing an API definition
• Postman now generates docs from OpenAPI 3.0 definitions

API headers

API headers contain the metadata that is sent along with an API request or response. They provide essential details that help the client and server communicate more effectively—and enable developers to customize and optimize the API's behavior. Some common examples of API headers include:

• Authorization: Used to provide authentication information, such as a token or username and password.
• Content-Type: Specifies the format of the data being sent in the request or response, such as JSON or XML.
• Accept: Specifies the preferred data format that the client expects to receive in the response.
• Cache-Control: Specifies caching directives, such as max-age and no-cache, for the response to be cached or not.
• User-Agent: Specifies information about the client making the request, such as the browser or device used.

API key

An API key is a unique identifier that is used to authenticate and authorize access to an API. An API key is passed along with each API request to identify the client and ensure it has the necessary permissions to interact with the relevant endpoint. Some API keys grant full access to the API, while others may provide read-only access, write access, or access to specific features or endpoints in the API. They may also be configured with usage limits that restrict the number of requests per day, or with expiration dates to ensure that access is revoked after a certain period of time.

API keys are commonly used by developers to access APIs that are provided by third-party services. By requiring an API key, the API provider can control access to their API, monitor usage, and restrict access to authorized users.

API platform

An API platform is a software system with integrated tools and processes that allow teams to effectively build, manage, publish, and consume APIs. An API platform helps API producers manage the entire API lifecycle—from design to production—while engaging directly with API consumers. API platforms complement and enhance existing workflows through integrations with source code management tools, CI/CD pipelines, cloud infrastructure, and APM solutions. They also enable leaders to create and implement API governance and security strategies that foster collaboration, promote consistency, and reduce risk.

Learn more about API platforms →

API testing

API testing is the process of validating that an API is working as expected. API testing can be performed manually on an ad-hoc basis, or it can be automated with a testing tool that executes test scripts at predetermined intervals or in response to events. Traditionally, API testing has occurred at the end of the development phase, right before changes are deployed to production, but an increasing number of teams are running tests earlier in the API lifecycle. This approach to API testing, which is known as "shifting left," supports rapid iteration by enabling teams to catch and remediate issues as soon as they are introduced.

Learn more about API testing →

API-first

API-first is a development model in which applications are conceptualized and built as a collection of internal and external services that are delivered through APIs. This strategy treats APIs as crucial infrastructure components, and it allows teams to leverage private, partner, and public APIs to bridge the gaps between small, discrete chunks of code to create applications that are powerful, resilient, and able to meet user needs.

Learn more about API-first →

CORS

CORS, which stands for Cross-Origin Resource Sharing, is an HTTP header-based security feature that allows web pages to make requests to a different origin (i.e., a domain, protocol, or port) than the one from which the page originated.

When a web page makes a request to a different origin, the browser sends a pre-flight request to the server to check if it allows the request. The server responds with a set of CORS headers that specify whether the request is allowed, and if so, what types of requests, origins, headers, and methods are permitted.

CORS is important for security because it prevents malicious web pages from accessing sensitive data on other websites. For example, if a malicious web page was able to access your online banking account by sending requests to the bank's server, it could steal your personal information and perform unauthorized transactions. By implementing CORS, web browsers can prevent this type of attack by blocking requests from untrusted origins.

CRUD

CRUD, which stands for Create, Read, Update, and Delete, refers to a set of basic operations that can be performed on data in a database or other data storage system. CRUD operations are most frequently performed with five standard HTTP methods: POST, GET, PUT, PATCH, and DELETE. CRUD is a fundamental concept in software development and is used to manage data in a wide range of applications, such as content management systems, e-commerce websites, social media platforms, and more.

The CRUD operations are:

• Create: This operation is used to create data in a system, such as a new user account, a new blog post, or a new product. It is typically performed with the POST method.
• Read: This operation is used to retrieve data, such as a list of all users, a single blog post, or a specific product. It is typically performed with the GET method.
• Update: This operation is used to make modifications to existing data, such as updating a user's account information, editing a blog post, or changing the price of a product. It is typically performed with the PUT or PATCH methods.
• Delete: This operation is used to remove data, such as a user account, a blog post, or a product. It is typically performed with the DELETE method.

cURL

cURL is a command line tool that facilitates the transfer of data to or from a server using various protocols, such as HTTP, HTTPS, FTP, FTPS, SCP, and SFTP. cURL is available on most operating systems, including Linux, macOS, and Windows, and it can be used in a terminal or from within a script. cURL is widely used to test APIs, debug network issues, and automate repetitive tasks. It is also used to add headers and cookies to requests, follow redirects, specify authentication credentials, and verify SSL/TLS certificates.

DELETE

DELETE is a standard HTTP method that is used to delete data on a server. When a client sends a DELETE request, it is requesting that the resource at the specified URL be removed. If the server accepts the request, it will delete the resource and return a response indicating success. For instance, a delete request to the /users/123 endpoint should result in the removal of the user resource with an ID of 123.

It's worth noting that the DELETE method is powerful and should be used with caution to avoid accidentally deleting important data. Proper authentication and authorization mechanisms should be put in place to ensure that only authorized users can delete data.

Endpoint

An API endpoint is a URL that is used to retrieve, create, update, or delete data on a server. A well-designed API should have clear and intuitive endpoints that provide a consistent and predictable way for clients to interact with the server's resources. For example, a simple RESTful API might have the following endpoints:

• /users - to retrieve a list of all users (GET)
• /users/:id - to retrieve a specific user by ID (GET)
• /users - to create a new user (POST)
• /users/:id - to update an existing user by ID (PUT)
• /users/:id - to delete an existing user by ID (DELETE)

In this example, the endpoints define the actions that a client can perform on the server's user resource. Some endpoints include an ID parameter, which enables the client to specify which specific user resource it would like to interact with. The endpoints are accessed using standard HTTP methods, such as GET, POST, PUT, and DELETE.

GET

GET is a standard HTTP method that is used to retrieve data on a server. When a client sends a GET request, it uses a specific URL to identify the resource it wants. If the server accepts the request, it will return a response that includes the resource's representation in HTML, JSON, XML, or another format. For example, if the client sends a GET request to /users/123, the server will return the user resource with an ID of 123.

The GET method is typically considered a safe method, as it does not modify the server's resources. Instead, the server simply retrieves and returns the requested data.

HTTP

HTTP, which stands for Hypertext Transfer Protocol, is a standardized protocol for transmitting data—such as HTML pages, images, and videos—between clients and servers on the internet. HTTP works on the client-server model, where the client sends an HTTP request to the server and waits for a response. HTTP uses a standard set of request methods, such as GET, POST, PUT, and DELETE, to specify the type of action the client would like to perform on a given resource.

HTTP requests are typically initiated by clicking on a link, entering a URL into a browser's address bar, or submitting a form. The browser sends the request to the server, which processes the request and sends a response back to the client. The response includes a status code that indicates whether the request was successful. If so, the response will also contain the actual data that was requested.

Additional resources:

• How to choose HTTP or gRPC for your next API
• A beginner's quick guide to APIs: definitions and types

JSON

JSON, which is pronounced "JAY-son" and stands for JavaScript Object Notation, is a lightweight, text-based data format that is easy for humans and machines to read and write. JSON is based on the JavaScript programming language syntax and uses key-value pairs to represent data objects. JSON keys are strings, and their values can be strings, numbers, booleans, arrays, or another JSON object. The key-value pairs are separated by commas, and objects are enclosed in curly braces.

Here is an example of a JSON object that represents a person:

{
  "name": "John Smith",
  "age": 35,
  "address": {
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zip": "12345"
  },
  "email": "john.smith@example.com",
  "phoneNumbers": [
    {
      "type": "home",
      "number": "555-1234"
    },
    {
      "type": "work",
      "number": "555-5678"
    }
  ]
}

In this example, the JSON object has several key-value pairs, including name, age, address, email, and phoneNumbers. The address field is itself an object, with several nested key-value pairs, while the phoneNumbers field is an array of objects.

JSON has become a popular format for transmitting data over the internet because of its simplicity, compactness, and readability. It is supported by many programming languages and platforms, and it is often used in RESTful APIs to transmit data between servers and clients.

Additional resources:

• How to test JSON properties in Postman
• When and how to use JSON serialization in Postman
• JSON Schema in production: how you can use it today

OpenAPI

OpenAPI (previously known as Swagger) is the most widely used specification format for describing and documenting an API's endpoints, methods, parameters, responses, and more. The OpenAPI specification provides a rich ecosystem of tools to work with APIs, and it can be used to generate client libraries, documentation, and other artifacts.

Additional resources:

• Postman joins the OpenAPI Initiative
• How Postman uses the OpenAPI specification
• Postman now supports OpenAPI 3.1

Parameters

Parameters are the variables that are passed to an API endpoint to provide specific information or instructions for the API to process. These parameters can be included in the API request as part of the URL, in the query string, or in the request body.

API parameters can be used to filter, sort, or paginate data, provide authentication credentials, or specify the format of the response. For example, a weather API might accept a city parameter to return the weather forecast for a specific city, or a search API might accept a query parameter to filter search results by a specific keyword.

There are several types of API parameters, including:

• Path parameters: Used to identify a specific resource in the URL path, such as the ID of a user or the name of a product.
• Query parameters: Used to filter or modify the response data, such as by specifying a date range or sorting the results by a particular field.
• Header parameters: Used to provide additional metadata or authentication credentials, such as an API key or an access token.
• Request body parameters: Used to provide additional data to the API, such as information that is required to create or update a resource.

PATCH

PATCH is an HTTP method that is used to update or modify an existing resource. It is similar to the PUT method, except that PUT replaces the entire resource, while PATCH only applies a partial update to the resource. For instance, if you have a user resource with fields for name, email, and password, but you only want to update the email value, you can use the PATCH method to send a request that only includes the new value for the email field. The PATCH method is therefore a powerful tool for updating resources flexibly and efficiently.

POST

POST is an HTTP method that is typically used to create new resources. For example, a POST request to a /user endpoint will create a new user record in the database that is based on the data included in the request body. The POST method often causes a change in state or side effects on the server.

One important characteristic of the POST method is that it is considered "non-idempotent," which means that multiple identical requests may have different effects. For example, if you submit the same POST request twice, you will end up with two resources with different IDs, rather than a single updated resource. This behavior is different from that of idempotent methods like GET and PUT, which produce the same result regardless of how many times they are executed.

PUT

PUT is an HTTP request method that is used to replace an existing resource with an updated version. In contrast to the PATCH method, in which only the fields or properties that are included in the request body are updated, PUT replaces the entire resource with the data that is sent in the request body. This means that any fields or properties not included in the new representation are deleted, and any new fields or properties are added. This behavior can make PUT requests quite large, especially for complex resources with many fields or properties.

Like all HTTP methods, the PUT method returns a response that includes a status code and an optional response body. The response typically includes a representation of the updated resource, or a confirmation message indicating that the update was successful.

RAML

RAML, which stands for RESTful API Modeling Language, is a specification language that is used to define RESTful APIs. It provides a way to document the resources, methods, parameters, and responses of an API in a structured and machine-readable format. RAML supports a wide range of features, including URL routing, request/response models, media types, security, and more. It is also highly extensible, with a range of tools and libraries available for developers to build and customize their own RAML-based solutions.

Additional resources:

• RAML and API Blueprint: where are they now?
• Syncing your OpenAPI, RAML, and GraphQL schema to GitHub with Postman

RPC

RPC, which stands for Remote Procedure Call, is a technique for building distributed systems that enables programs to call functions on other machines as if they were local. In an RPC system, a client program sends a request to a remote server program to perform a specific procedure, passing any necessary input data. The server then processes the request and returns a response with any output data. The client program can then continue its execution based on the response it receives.

The RPC protocol abstracts the details of the network communication between the client and server, allowing them to communicate as if they were both on the same machine. The protocol can be implemented using a variety of transport protocols, such as TCP or UDP, and can use different encoding schemes to represent the data being transmitted, such as JSON or XML.

One of the main advantages of RPC is that it allows programs to work together without knowing the details of each other's implementation. This makes it easier to build complex distributed systems, as each team can focus on its own program's functionality.

Additional resources:

• How to choose HTTP or gRPC for your next API
• Postman v10 and gRPC: what you can do

Shift-left testing

Shift-left testing is the practice of running tests at every stage of the development cycle. Traditionally, testing has occurred right before new features are deployed to production, but this approach can result in unexpected delays as teams struggle to fix issues that have become deeply ingrained. With shift-left testing, teams can catch issues as soon as they are introduced, which helps them iterate quickly and confidently. Automation plays a key role in the shift-left approach, as it lets developers automatically execute tests within CI/CD pipelines whenever they push new code.

Additional resources:

• Shifting left with Postman
• API test automation overview

SOAP

SOAP (Simple Object Access Protocol) is a messaging protocol for exchanging structured data over the internet. It is based on XML and is used to facilitate communication between different applications and systems, especially in a distributed environment.

In a SOAP-based system, messages are sent between a client and a server in the form of XML documents. Each message consists of a header and a body, with the header containing metadata and the body containing the actual data being transmitted. The messages are usually transmitted over HTTP or other protocols, and can be used to exchange data between different programming languages and platforms.

SOAP is often used in enterprise environments where complex transactions and reliable messaging are important. It includes support for advanced features such as message routing, security, and reliability, making it well-suited for financial transactions, supply chain management, and other business-critical processes.

Additional resources:

• API 101: SOAP vs. REST
• API 101: What is a SOAP API?
• Using SOAP requests

Status codes

API status codes are HTTP status codes that are returned by an API to indicate the status of a client's request. These codes are used to provide information to the client about the outcome of the request and to help the client understand how to proceed.

Here are some of the most common API status codes and their meanings:

• 200 OK: The request was successful, and the server returned the requested data.
• 201 Created: The request was successful, and the server created a new resource.
• 204 No Content: The request was successful, but the server did not return any data.
• 400 Bad Request: The request was malformed or invalid.
• 401 Unauthorized: The client is not authorized to access the requested resource.
• 403 Forbidden: The client is authenticated but not authorized to access the requested resource.
• 404 Not Found: The requested resource was not found on the server.
• 500 Internal Server Error: The server encountered an error while processing the request.

API status codes can provide important information to the client, enabling it to respond appropriately to the server's response. For example, a client may retry a failed request if it receives a 5xx status code, or it may prompt the user to provide valid input if it receives a 400 Bad Request status code.

Webhooks

Webhooks enable applications to provide real-time notifications to other systems by sending an HTTP request to a specified URL when a particular event occurs. Webhooks are an efficient and scalable way to implement event-driven architectures because they eliminate the need to continuously poll an API for changes.

When an event occurs in an application, such as a new user account being created or a payment being made, the application can send an HTTP request to a pre-configured webhook URL with the relevant event data in the request payload. The system that receives the webhook can then process the event and take the appropriate action.

Webhooks support a wide range of use cases, including:

• Payment processing: Webhooks can be used to notify a service when a payment has been made or refunded.
• Messaging: Webhooks can be used to send real-time updates about messages sent and received by users.
• E-commerce: Webhooks can be used to notify a service when an order has been placed, updated, or canceled.
• Social media: Webhooks can be used to provide notifications when users interact with social media posts or messages.

Additional resources:

• Triggering runs with webhooks
• Custom webhooks

XML

XML (eXtensible Markup Language) is a markup language used to encode documents in a format that can be read by both humans and machines. XML documents are composed of markup tags that define the structure and content of the document. Each tag defines an element, which can contain text, other elements, or attributes that describe its properties. An XML document must have a root element that encloses all other elements in the document.

XML is widely used in web services and APIs as a data exchange format, particularly in the SOAP (Simple Object Access Protocol) and REST (Representational State Transfer) architectures. It is also commonly used for configuration files and data storage.

Some advantages of XML include its flexibility, extensibility, and the ability to validate data against a schema. However, it can be verbose and may not be as efficient as other data interchange formats, such as JSON.