Learn the fundamentals of APIs, complete with definitions, examples, and resources to get you up and running.
Just as user interfaces (UIs) help people interact with software, application programming interfaces (APIs) enable discrete software and services to interact with each other. In this guide, we take you through the fundamentals of this fascinating topic, complete with definitions, examples, and resources to get you started on the road to API nirvana.
An Application Programming Interface, commonly shortened to API, is a set of rules which determines how one software program can access the data or functionality provided by another software program.
APIs are an essential part of modern software development. They allow different systems and applications to communicate with each other and share functionality in a flexible and efficient way. They're used in a wide variety of contexts, including web development, mobile apps, and Internet of Things (IoT) applications.
APIs often come in the form of a library that a software developer can include in their code. This library provides a set of functions that can be called upon to perform various tasks. The API specifies the function calls, the inputs they accept, and the outputs they return.
Here's a simplified overview of how APIs work:
Let's go deeper with a real-world example. Imagine you're building an app that displays the weather from both your location and other places around the world.
To do this, you'll need a way to get the coordinates (latitude and longitude) of the your location or chosen destination, than match it against the weather forecast. You could manually enter this information as and when the user requests it, but that would be extremely time-consuming and prone to error.
Instead, you could use an API provided by a company that maintains a database of meteorological data. You could use this API to search for the weather forecast in your city and deliver the information in a matter of seconds.
In such a project, using an API would save you a lot of time and effort. As well, it would ensure that data is accurate and up to date. The API would access and query the database, while your app would simply display the information returned by the API.
Like the example above, you can use APIs in a multitude of scenarios to access a wide variety of data and functionality. You could use them to retrieve the latest news headlines, look up restaurants in your area, or look up information about a specific product.
Using an API typically involves the following steps:
| Step | Description |
|---|---|
| 1. Find an API | The first step in using an API is to find an API that provides the functionality you need. There are many APIs available on the internet, and you can search for APIs using search engines, developer portals, or API marketplaces. |
| 2. Read the documentation | Once you have found an API that you want to use, the next step is to read the API documentation. The documentation should provide information on the API's capabilities, the structure of the requests and responses, and any authentication or authorization requirements. |
| 3. Understand the API's terms of use | Before you begin using an API, it's important to understand its terms of use. These terms will specify limitations on how you can use the API, and how you can use and share the API's data. It may also explain whether the API is free or requires a paid subscription. |
| 4. Obtain an API key | Many APIs require you to obtain an API key before you can start using it. The API key is a unique identifier used to authenticate your API requests. You're given one after you sign up for the API or after you agree to the API's terms of use. |
| 5. Make API requests | Once you have an API key and have read the API documentation, you can start making API requests. The API request usually contains a URI that identifies the resource you want to access. It'll also have an HTTP verb (such as GET or POST) to specify the operation you want to perform. You can make API requests using a tool such as a command-line utility or a library in your programming language of choice. |
| 6. Process the API response | When you make an API request, the API server will send a response back to you. The response may include data, an error message, or a status code indicating the result of the operation. It's important to process the API response and handle any errors or exceptions that may occur. |
| 7. Follow best practices | Cache data to reduce the number of API requests, handle errors and exceptions gracefully, and respect the API's terms of use. By following best practices like these, you'll make sure that your use of the API is efficient, reliable and compliant. |
An API call is a request made to an API to access data or functionality. A client makes an API call and sends a request to the API server, and the server sends back a response. The request and response use a specific format and structure, and are transmitted using a specific protocol (such as HTTP).
To make an API call, you should have access to the API documentation. This documentation provides information on the API's capabilities, the structure of the requests and responses, and any authentication or authorization requirements. You may also need to obtain an API key or other credentials before you can make API calls.
An API key is a unique identifier used to authenticate API requests. API keys will typically track and control how you can use an API. They can also provide access to an API's data and functionality.
API keys guide the correct operation of an API as per the terms of use. They can limit the number of API requests that a client can make, for example. An API key can also track the usage of an API, or make sure that the data provided by an API is being used appropriately.
API keys are usually provided by the API provider and are required to make API requests. They can be generated and managed through the API provider's developer portal, and are often specific to a particular API or application.
API keys are typically present in the header of an API request, and are used to authenticate the request. Other authentication and authorization credentials, such as an OAuth token or a JSON Web Token (JWT), may also be used in tandem.
An API endpoint is a specific location on a server which can receive and respond to API requests. An API endpoint is identified by a URI (Uniform Resource Identifier) and is typically associated with a particular API or service.
APIs and webhooks are both ways that different software components can communicate with each other over the internet. However, they differ regarding how they work and when they are used.
As explained above, APIs are a set of rules and protocols that define how different software components can interact with each other. They provide a way for different systems and applications to communicate with each other, share data and functionality, and work together to perform tasks. To use an API, a client sends a request to the API server using a specific protocol (like HTTP) and gets a response. The client and server communicate through a series of requests and responses, and the API defines the specific format and structure of these messages.
How are APIs different from webhooks? Webhooks are a way for a server to send data to a client in real-time, without the client needing to make a request. When a specified event occurs on the server, the server can send a message to a specified URL. The message is usually in the form of an HTTP POST request. The client can then process the message and act based on the data received. Webhooks are often used to enable real-time communication and event-driven architectures, and can be used to build more efficient and responsive systems.
Both APIs and webhooks are incredibly useful tools for building interconnected systems, but they apply to different situations and for different purposes. To learn more about the differences, see our post comparing Webhooks vs APIs.
APIs are extremely useful for situations where communication and interoperability between different systems and applications is needed. Here's a few examples of common applications for APIs:
APIs are a core component of web-based applications which are accessible from any device with an internet connection. For example, an API would allow an app in your web browser to communicate with a server-side application. Alternatively, it would enable a web-based application to retrieve data from a database.
You can use APIs to build dedicated mobile apps that can access data and functionality from a server-side application or cloud service. For example, a social media app on your smartphone might use an API to retrieve a user's feed, or to publish a new post.
APIs also enable communication between IoT devices and other systems and applications. For example, an API might facilitate communication between a smart thermostat and a home automation system. Elsewhere, it could enable an IoT device to send data to a cloud service for analysis.
APIs allow different applications and services to work together and share data. For example, a customer relationship management (CRM) system might use an API to integrate with a marketing automation platform. Or a project management tool might use an API to integrate with a time-tracking application.
APIs are extremely popular for building microservices architectures. A microservice is the result of breaking down a large application into smaller, independent services that communicate with each other through APIs. With distinct parts, different services can be developed, tested, and deployed independently, which makes it easier to scale and maintain the overall application.
There are many different types of APIs. Some common categories include:
| Type | Description |
|---|---|
| Open APIs | These are made available to developers outside the organization that created them. Open APIs provide access to a specific product or service, and are available to anyone who agrees to the terms of use. They are also known as external or public APIs. |
| Internal APIs | These are used within an organization to share resources and functionality between different teams or systems. They aren't usually available to developers outside the organization. |
| Partner APIs | These APIs are available to a specific group of developers who have a business relationship with the organization that created the API. Usually this group consists of partners or third-party developers. |
| Composite APIs | These are APIs that combine multiple underlying APIs into a single interface. They provide a simplified way for developers to access multiple resources or functionality in a single call. |
It's worth noting that these categories aren't mutually exclusive, and an API may fall into more than one category depending on how it's used.
An API architecture refers to the overall design and structure of an API, including the way it's organized, the types of requests it supports, the data formats and protocols it uses, and any security or authentication mechanisms it employs. A well-designed API architecture should be flexible, scalable, and easy to use, with clear documentation and a robust support system for developers. There are several types of API architectures in widespread use. Here's an overview of the most common:
REST APIs are a type of web API that uses HTTP requests to manipulate data. They're designed to be lightweight and flexible, and are great for building web services that are scalable and easy to maintain. REST APIs use a fixed set of HTTP verbs to perform operations on resources that are identified using a URI (Uniform Resource Identifier). Examples of these verbs are GET, POST, PUT, and DELETE. REST APIs are also useful for creating CRUD (Create, Read, Update, Delete) applications.
SOAP APIs are a type of web API that uses XML (Extensible Markup Language) to encode messages. They're designed to be extensible and neutral, for building web services that are interoperable between different programming languages and platforms. SOAP APIs use a standardized messaging format and transport protocol (usually HTTP) to send and receive messages.
RPC APIs are a type of API designed to make it easy to invoke methods on remote objects, which is useful for building distributed systems. RPC APIs are based on a client-server model. The client sends a request to the server to execute a specific procedure or function, and the server returns the result to the client.
GraphQL is a query language and runtime developed by Facebook as an alternative to REST and SOAP APIs.
GraphQL creates a representation of your data that is designed to feel familiar and natural, like a visual graph. The graph part of GraphQL describes a data structure of a collection of objects — or nodes — that are connected to each other through a set of links, or edges. Relationships between different objects can be represented in a user interface as a result of this graph structure. The key concept is that the data structure is non-linear, meaning that one object can be connected to more than one other object, and relationships can also be circular.
So what are the benefits here? Using GraphQL, clients can request only the data they need rather than receiving a fixed set of data from a server. It's flexible and efficient, while also being easy to use and learn, with a simple syntax and powerful tools for building and testing queries.
A web API is an API that's accessed over the internet using HTTP (Hypertext Transfer Protocol). Web APIs allow different systems and applications to communicate with each other over the internet. Web applications built with web APIs are accessible from any device with an internet connection.
You might assume that all APIs are web APIs, but this isn’t the case. Some APIs function only within the confines of a computer operating system, allowing local programs and routines to interact with one another.
It may surprise you to learn that application programming interfaces predate the existence of the World Wide Web. As far back as the 1940s, in fact, with the emergence of the first computers.
British computer scientists Marice Wilkes and David Wheeler were working on a software library for the Electronic Delay Storage Automatic Calculator (EDSAC). The pair programed EDSAC to accept a variety of instructions like add, subtract, print, load, and store. This behavior is similar to how modern web APIs interface with data today, for example, "add blog post," "delete blog post," or "get blog post information."
Wilkes and Wheeler documented the uses of EDSAC via a catalog of notes about its functionality and how to integrate it with other programs. It was the first example of the type of API documentation we know today.
APIs can be created by any group or individual, including software companies, government agencies, non-profit organizations, and open-source projects. Some well-known companies that create APIs include the following:
These are a few examples. There are many other companies and organizations that create APIs for a wide variety of purposes, including social media, finance, healthcare, and education.
An API-first CMS (Content Management System) is a type of CMS that exposes its content and functionality through APIs. They provide a robust and flexible set of APIs to build a range of applications and integrations.
An API-first CMS is flexible and modular by design. They leverage a microservices-based architecture that allows different components of the CMS to be developed, tested, and deployed independently. It's also typically designed to be scalable and resilient, with the ability to handle large amounts of traffic and data without performance degradation.
API-first CMSs are often used to build modern web and mobile applications that require flexible and scalable content management capabilities. They can also build integrations with other systems and applications, or enable real-time communication and event-driven architectures.
Contentful provides a set of APIs to build and manage content-driven applications and websites.
To use Contentful's APIs, you'll need to sign up for a Contentful account and create an API key. You can then use the API key to make API requests to access and manipulate content stored in Contentful.
Here's an overview of the steps you can follow to use Contentful's APIs:
| Step | Description |
|---|---|
| 1. Sign up for a Contentful account | You'll need to create a Contentful account and sign up for a free trial account or a paid plan depending on your needs. |
| 2. Create an API key | Once you have a Contentful account, navigate to the "API Keys" section in your account settings. Here you can create multiple API keys for different purposes, such as for different environments or applications. |
| 3. Read our API documentation | Contentful provides extensive documentation for our APIs. We provide detailed information on the structure of the requests and responses, and examples of how to use the APIs. You should familiarize yourself with the documentation before you start using the APIs. |
| 4. Make API requests | You can use a variety of tools and technologies to make API requests to Contentful's APIs. Some common options include command-line utilities such as cURL, libraries in programming languages such as JavaScript or Python, or web-based APIs such as GraphQL. |
| 5. Process the API response | When you make an API request to Contentful, the API server will send a response back to you. The response may include data, an error message, or a status code indicating the result of the operation. It's important to process the API response and handle any errors or exceptions that may occur. |
To learn more about APIs, integration, or how to use Contentful APIs for creating and managing your content, sign up for a free Contentful membership and begin creating your space.
