What is an API?

An application programming interface (API) is a set of protocols that enable disparate software systems to communicate with each other regardless of their programming language or platform. It is sometimes said that APIs “help machines talk to other machines” because, by communicating through a structured set of rules, APIs let you interact with systems programmatically instead of going through a web interface.

APIs also enable you to integrate new solutions with existing applications and automate processes. There are thousands of APIs available on the web, many of which are free to use. You can turn to an API directory like the Postman API Network or visit the website of the service or product you want to integrate with to check if they have an API available.

While there are multiple types of API architectures, such as SOAP (Simple Object Access Protocol) APIs, GraphQL APIs, and RPC (Remote Procedure Call) APIs, this guide will focus on one of the most common: Representational State Transfer (REST). Web services that conform to the REST API style are known as RESTful APIs. RESTful APIs use HTTP and look a lot like a webpage URL.

What is an example of an API?

You have probably already encountered APIs in action without even realizing it. Imagine you’re ordering lunch via the website of your favorite taco restaurant. At checkout, you need to enter your delivery address. Almost as soon as you start typing your address in the search bar, it auto-completes the city, state, and zip code. Next, you go to enter payment information, and you notice the payment fields are processed by a trusted mobile payment service. Finally, after you place your order, you can sign up for a loyalty program and earn rewards based on your order by simply signing up using your preferred social media platform.

The address auto-completion, payment processing, and social media sign-up are all examples of API integration. Instead of having to create each of these components from scratch, the website uses the Google Maps API to easily collect delivery addresses, the Square API to integrate with Square’s payment processing system, and the Facebook API to quickly create rewards accounts.

How do REST APIs work?

REST APIs use HTTP requests and responses to exchange information across the internet. This is beneficial because the web client making the request and the API server responding speak a common language. The message request and response themselves use a common HTTP web protocol.

There are many common use cases for REST APIs, typically along the lines of standard Create, Retrieve, Update, and Delete (CRUD) database functions. For example, REST APIs can perform create actions, using things like the Facebook API to create a new rewards account. They can also retrieve data by using things like Google Maps API to retrieve addresses. 

The anatomy of an API request

Let’s get into the anatomy of an API request, which has five components:

The base URL: The prefix for the endpoint.

The endpoint: This tells the request where to go.

The method: Determines the type of request taking place.

The headers: Provide information that helps the client and server talk to each other.

The body: Contains the information you want sent to the server.

So, with the basics covered, let’s dig a little deeper.

Here is an example of an endpoint for the Google Maps Places API:

https://maps.googleapis.com/maps/api/place/autocomplete/

This endpoint has two components. The first is the base URL; the domain where the API is served. In this example, https://maps.googleapis.com is the base URL. The path of the endpoint determines the resource you’re requesting. Here, we’re requesting a specific resource of the Google Maps Places API called Autocomplete, so we have this path: /maps/api/place/autocomplete

If you’re wondering why this looks a lot like a URL, that’s because it is. Remember, this request is happening over HTTP. If you put this in your browser, you’ll get a very basic HTML page with the response formatted in different ways depending on the API, with JSON being one of the most common response formats.

However, to actually do something with the API, you need a few other components. The first is a method. Methods are predefined keywords that must be included in every request. The most common methods are related to the CRUD operations: POST (create), GET (read), PUT (update), and DELETE. The method tells the API what you want done, and each endpoint expects a certain method.

What is a request header?

Another component used to call an API is a request header. A request header is actually an HTTP header. It provides additional information about the context of the request. For example, a request header might indicate the preferred language to be used for the response. Most APIs also require authentication headers, which provide authentication information to the client. These are like a personal certificate that shows the person using the API is legitimate and helps ensure API security. 

Depending on the method, you may need to define additional data in the body of the request. For example, if you are creating something using a POST method, there might be data fields used during creation that you need to input.

As an example, let’s consider the user registering for an awards account. The user fills out certain fields on your website to create their account. In the backend, an API is invoked, and the details the user entered are used in the body of the request:

{
"first_name": "Kris",
"last_name": "Owner",
"email": "krisowner@email.com",
}

Calling an API

Now that you know what makes up an API request, how do you call one? To instantly test an API and see the response, you might send the request via curl or an application such as Postman.

For example, let's say you wanted to retrieve the details for a specific user account. The response may look something like the following:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "comment": "",
  "created_at": "2020-04-27T19:40:49+00:00",
  "deleted_at": null,
  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "first_name": "Kris",
  "last_name": "Owner",
  "email": "krisowner@email.com",
}

The response returned depends on the API and the request you made. 

Let's break this down further. The first line contains the status, which in this case is 200 for success. In the next line, the Content-Type header indicates the format of the information you requested, which in this case is JSON. Finally, the body of the response contains the details about the user.

Here, we have demonstrated calling an API for a simple retrieval. You could probably get the same information by logging in via the web interface of your application. The more likely use case for calling an API is incorporating the request into your application and doing something with the data you receive in the response.

How do you ensure API security?

When it comes to APIs, security is critical. You need to keep your sensitive data safe and make sure only authorized people can access your API. In addition to the authentication headers discussed above, API keys are a common way to authenticate clients and ensure that only the right people can get in. OAuth (Open Authorization) is another option – it's a standard protocol that lets users grant third-party applications access to their resources without having to share their login credentials. Rate limiting how many requests can be handled in a given timeframe is also important to prevent abuse and keep your API running smoothly. HTTPS encryption is a must-have to keep all your API communication secure in transit and protect sensitive information from falling into the wrong hands.

Why is API documentation important?

If you want developers to use your API effectively, you need clear and comprehensive documentation. It's like a roadmap that helps them understand how to make the most of your API. Your documentation should cover all the important details, like endpoints, request and response formats, authentication requirements, and even provide some code snippets to get them started. It's also a good idea to include information about error handling, rate limits, and any specific best practices or constraints that come with your API. Good API documentation reduces the learning curve and helps developers to integrate the API seamlessly into their applications without any hassle.

What is API versioning?

As your API grows and evolves, versioning becomes a crucial part of the process. You want to be able to add new features and make changes without breaking any existing integrations. One way to do this is by including the version number right in the API URL, for example: /api/v1/resources. This way, it's clear which version of the API is being used. Another approach is to use versioning in the request header, so clients can specify which version they want. The key is to have a solid versioning strategy in place and make sure you communicate any changes to developers. Don't forget to provide migration guides when you introduce breaking changes.

Why do you need to perform API testing?

Testing your API is like giving it a full health check-up. You want to make sure it's reliable, performs well, and follows the required specifications. Unit testing is a great place to start, as it lets you test individual components of your API and make sure each function or method behaves as expected. 

Integration testing is another important step, which ensures that different parts of your API can play nicely together and give you the results you want. 

And if you really want to put your API through its paces, you can also perform load testing. Load testing helps you find any performance bottlenecks and makes sure your API can handle the expected amount of traffic. There are many automated testing tools and frameworks out there, like Postman, SoapUI, and JMeter, that can make API testing easier and help you catch potential issues early on.

What is API lifecycle management?

Managing your API throughout its entire lifecycle is key to its long-term success and maintainability. API gateways act like bouncers at a club – they provide a single entry point for all your API requests and handle vital tasks like authentication, rate limiting, and request routing. 

Versioning and deprecation (API discontinuation) strategies are also a big part of the API lifecycle. When you introduce a new version of your API, make sure you provide clear migration paths and let developers know when you plan to phase out older versions. And if you ever need to retire an API, give developers plenty of heads up so they can update their integrations. A little bit of planning and communication goes a long way in keeping your API running smoothly and avoiding any major disruptions for users.

How to work with the Fastly API

The Fastly API is a RESTful API that provides access to all the features available through the Fastly web interface.

By using the API, you can work with the objects related to Fastly services and accounts in whatever way is most convenient for you, whether that’s integrating with your existing workflows or automating oft-repeated or cumbersome processes. For example, you might use Fastly’s real-time analytics API to integrate Fastly analytics into your custom analytics dashboard. Or, you may choose to set up an automated purging process. The possibilities are limited only by your imagination (and your programming skills).

Learn more about Fastly’s API in our API reference documentation. Best of all, Fastly API is free to use with your Fasly account.