The 2023 State of the API survey is open!
Make your voice heard in the world's biggest API survey
Use this API glossary to build a strong API vocabulary and learn more about how APIs are designed, developed, deployed, and managed.
An API, or an application programming interface, is a set of code-based instructions that enable different software components to communicate and share data. Developers use private, partner, and public APIs to bridge the gaps between small, discrete chunks of code in order to create applications that are powerful, resilient, and able to meet user needs. APIs can be implemented with a wide range of architectures, protocols, and programming languages, which makes a strong API vocabulary essential for anyone who works with software. Use this API glossary to boost your API literacy and learn more about how APIs are designed, developed, deployed, and managed.
An API client is a development tool that makes it easier for producers and consumers to explore, test, and debug APIs. Traditional approaches to calling an API require a significant amount of specialized knowledge; for instance, the API user must know a programming language, understand the API's framework and protocol, and be able to interpret the response. This time-consuming process not only slows down API development and integration efforts, but also prevents people with less technical backgrounds from working with APIs. API clients abstract away some of this complexity, lowering the barrier to entry for API-related work and enabling developers to stay focused on big-picture goals.
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.
An API gateway is a server that acts as an entry point for clients to access and interact with multiple microservices and backend systems. API gateways are an important component of microservice-based architectures, as they provide a centralized point of control for many common tasks that would otherwise be performed by each individual microservice. For instance, API gateways typically handle request routing, protocol translation, security, rate limiting, caching, load balancing, and API versioning. They can also provide various features—such as authentication, authorization, and analytics—to monitor and manage the usage of APIs. These capabilities enable developers to create a more scalable, resilient, and efficient system.
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.
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.
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.
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.
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.
A cache is an infrastructure component that temporarily stores frequently accessed data so that it can be served more quickly and efficiently. When an API client makes a request, the server can check the cache to see if the requested data is already available. If it is, the server can return the cached response directly to the client, without having to execute the full request again. This approach significantly improves the performance of the API by reducing the number of requests that the server needs to process, which minimizes latency and improves scalability.
There are many types of cache implementations, such as in-memory caches, disk-based caches, or distributed caches. They can also be configured with various caching policies— such as time-to-live (TTL), cache eviction, and cache invalidation—to ensure that the cached data remains fresh and up-to-date.
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, 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 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 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
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.
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 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
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.
GraphQL is an open source query language for APIs that was created by Facebook in 2012. With GraphQL, clients interact with a single endpoint and specify the exact data they need, without having to chain multiple requests together. This approach reduces the number of round trips between the client and the server, which can improve performance—especially on slow or unreliable network connections. Additionally, GraphQL does not return data the client didn't ask for, which improves efficiency by reducing the amount of data that is transferred.
GraphQL also provides strong typing and validation of the request and response data, which makes it easier for API developers to safely evolve their APIs over time.
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.
Here is an example of a JSON object that represents a person:
"name": "John Smith",
"street": "123 Main St",
In this example, the JSON object has several key-value pairs, including
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.
A microservice is a small service that performs a single business function and communicates with other microservices through APIs. Each microservice is managed independently of one another, which can speed up the development and deployment process and make it easier to scale and maintain the system.
Microservices are often designed to be stateless, which means they do not maintain any session state between requests. Statelessness enables horizontal scalability, in which more instances of the same microservice can be added to handle increased load. Microservices can also be written in different programming languages and deployed on different platforms, which makes it easy to use the right tool for the job.
However, microservices also come with some challenges, such as increased complexity and reduced visibility. For instance, a microservice architecture consists of many small services that communicate with one another, which means that a small change in one microservice can have significant consequences on the microservices it interacts with. The distributed nature of a microservice architecture also makes it harder to test, monitor, and debug any issues that may arise.
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.
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 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 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 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, 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.
REST (Representational State Transfer) is an architectural style for building web services and APIs. In a RESTful architecture, resources are identified by URIs (Uniform Resource Identifiers), and operations are performed on those resources using standard HTTP methods such as GET, POST, PUT, and DELETE. The state of a resource is represented in JSON or XML, which is transferred between the client and server in the HTTP request and response bodies.
One of the key principles of REST is the separation of concerns between the client and server. The server is responsible for managing the resources and performing the requested operations, while the client is responsible for generating requests and interpreting the responses. This allows for greater flexibility and modifiability, as changes to the server do not necessarily require changes to the client.
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.
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.
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.
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 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.
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.