APIs, short for Application Programming Interfaces, are software-to-software interfaces. Meaning, they allow different applications to talk to each other and exchange information or functionality. This allows businesses to access another business’s data, piece of code, software, or services in order to extend the functionality of their own products — all while saving time and money.
Now that you understand the benefits, you might be wondering how you can exactly use an API to request and get data from another application. That’s where API calls come in.
![Download Now: How to Use an API [Free Ebook]](https://no-cache.hubspot.com/cta/default/53/1cbd6f4c-4566-446c-852a-0a9dae73e987.png)
What is an API Call?
An API call is the process of a client application submitting a request to an API and that API retrieving the requested data from the external server or program and delivering it back to the client.
Let’s say your app uses Facebook APIs to extract data and functionality from the platform. In that case, when broadcasting a live Facebook video stream, creating a post, or building a custom dashboard for your ads, you are actually making an API call.
Now that we understand what an API call is, let’s break down the process of making one.
How to Make API calls
- Find the URI of the external server or program.
- Add an HTTP verb.
- Include a header.
- Include an API key or access token.
- Wait for the response.
1. Find the URI of the external server or program.
To make an API call, the first thing you need to know is the Uniform Resource Identifier (URI) of the server or external program whose data you want. This is basically the digital equivalent of a home address. Without this, you won’t know where to send your request.
The HubSpot API’s URI, for example, is https://api.hubapi.com.
It’s important to note that most APIs have different endpoints, each with their own end paths. For example, let’s say you want to stream public tweets in real-time. Then you could use Twitter’s filtered stream endpoint. The base path, which is common to all endpoints, is https://api.twitter.com. The filtered stream endpoint is /2/tweets/search/stream. You can either add that to the end of the base path, or just list the endpoint in your request.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
2. Add an HTTP verb.
Once you have the URI, then you need to know how to formulate the request.
The first thing you need to include is a request verb. The four most basic request verbs are:
- GET: To retrieve a resource
- POST: To create a new resource
- PUT: To edit or update an existing resource
- DELETE: To delete a resource
For example, let’s say you use NREL’s Alternative Fuel Station’s API and want to see a list of the nearest alternative fuel stations in Denver, Colorado. Then you’d make a GET request that might look like:
GET https://developer.nrel.gov/api/alt-fuel-stations/v1/nearest.json?api_key=XXXXXXXXX&location=Denver+CO
This tells the server to search the database to find a list of alternative fuel stations in Denver. If that list exists, the server will send back a copy of that resource in XML or JSON and an HTTP response code of 200 (OK). If that list doesn’t, then it will send back the HTTP response code 404 (not found).
Here’s a look at the output in JSON:
If you’re not familiar with JSON, that might look intimidating. So you can use Excel to make the call and get a simple list of five alternative stations.
3. Include a header.
The next thing you need to include is a header, which tells the API about your request and the response you’re expecting. Including a header ensures the API understands what you’re asking and responds in a way that’s expected and easy for you to understand and use. Three common headers are user-agent, content-type, and accept. Let’s define each below.
User-Agent
This header enables servers to identify the application, operating system, vendor, and/or version of the user agent making the request.
For example, let’s say you want your application to work with New Relic's RESTful APIs. Then you need an HTTP agent to manage the information exchange between your application and New Relic and you need to identify that integration. In that case, you’d submit the following user-agent header in Java using the GET verb:
get.setHeader("User-Agent", "my-integration/1.2.3");
Content-Type
This header explains what type of information is in the body of the request. It might explain that the request was formatted in XML, for example, or JSON. Without this header, the API might receive your request and not understand what it is or how to decode it. As a result, you won’t get a response.
Accept
This header explains what format you’d like to receive your response back from the API. Without this header, the API could return the data requested in XML when you wanted it in JSON, or vice versa.
It’s important to note that an API might not be capable of returning data in the format you requested. That might be frustrating but you’ll still receive a response. So you should always include this header in your API call in case you can get the exact response you want.
4. Include an API key or access token.
An API key and access token serve the same purpose: they are unique identifiers used to authenticate calls to an API. Made up of a string of letters and numbers that identify the client application making the request, an API key or access token is used to grant or deny requests based on the client’s access permissions, and track the number of requests made for usage and billing purposes.
To make an API call to Google’s Cloud Natural Language API, you must include an API key as a query parameter. For example, let’s say you want to find named entities (ie. proper names and common nouns) in a body of text. Then you’d make the following API request, replacing API_KEY with your actual API key:
POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY
5. Wait for a response.
Now all that’s left to do is wait for a response from the API. You can expect a status code that lets you know the request was either processed successfully or unsuccessfully. In the latter case, the status code will explain the issue so you can correct it and try again. The most common codes are 2XX codes (“success codes”) and 4XX codes (“error codes”). Let’s take a brief look at some of the most common:
2XX Codes
These codes convey that the server has received the client’s request and processed it successfully. Here are the most common examples:
- 200 OK: The request was successful.
- 201 Created: The resource has been created on the server. This response is typically returned for POST requests.
- 202 Accepted: The request has been received but is still being processed.
- 204 No Content: The request has been successfully processed but no content will be returned.
4XX Codes
These codes convey that the client’s request has an error. It’s possible that the request is written incorrectly, or the resource which the client is requesting doesn't exist.
- 400 Bad Request: There is something wrong in the client’s request.
- 401 Unauthorized: The client is not authorized to make this request.
- 403 Forbidden: The request is correct but can’t be processed. Likely, the problem is that the client does not have required permissions.
- 404 Not Found: The resource being requested doesn't exist.
Free Ebook: How to Use an API
Everything you need to know about the history and use of APIs.
- A History of APIs
- Using APIs
- Understanding API Documentation
- And more!
Download Free
All fields are required.
Test API Calls
There are APIs for seemingly everything today, from embedding Instagram photos on your ecommerce site to providing access to thousands of hotels on your blog.
With so many APIs to choose from, it’s important to evaluate them carefully in terms of functionality, reliability, performance, and security so you know they meet your app’s and user’s needs. If you’re the one developing, providing, and maintaining an API, then testing is equally important. Testing frequently will ensure the API is functional and meets consumer expectations.
Now that we understand the importance of API testing, let’s define what it is exactly.
How to Do API Testing
API testing consists of making API calls to different endpoints, getting responses, and validating the status codes, response times, and data in those responses.
This type of testing is usually performed by a software tool or web service, like ReqBin. The process is relatively similar, but the exact steps will vary depending on which tool or service you use. Below are the steps to test an API using ReqBin. For the sake of this demo, we’ll test a free and open API.
1. Enter the URL of the API endpoint.
Let’s say you want to use The New York Times’s Article Search API to look up articles by the keyword “dog.” Then you’d use the following URL: https://api.nytimes.com/svc/search/v2/articlesearch.json?q=dog.
2. Select the appropriate HTTP method.
Since you want to retrieve the articles with this keyword, you’d use the GET method.
Note that if you were using the POST, PUT, or PATCH methods, then you’d enter data into the Content tab.
3. Enter your credentials in the Authorization tab.
If the API server requires authorization, then you need to enter your credentials in the Authorization tab. Let’s see what happens if you skip that step.
4. Click Send to submit your API request.
Once you submit your API request, you can see the returned API status code, response time, and content.
Notice in this case, you’ve received a 401 Unauthorized response. That’s because you need an API key to use this NYT API.
Once you’ve gotten an API key, you can continue testing by changing the API endpoint URL, HTTP method, and request data.
Making the Call
Now that you understand how to test an API call, you can start evaluating different APIs and narrow down which suit your app and users best. Then, when you’re ready to connect your application to the rest of the software world, you can make the call.
![What is Payload? A Quick Guide [+ Examples]](https://www.hubspot.com/hubfs/payload.webp)
