This guide is designed for people who have something they want to accomplish that requires using an API, but aren't quite sure how to get started. You already know why being able to work with an API is useful, and this guide will show you how to do that.

If that sounds like you, you're in luck! We're here to explain how to work with APIs, how to read API docs, and how to actually use the data coming back from an API.

We've brought a friend along to make the journey much easier.

Meet Slash

Slash the API Dog

Slash is Michelle's adorable, lovable dog. Michelle is a software engineer who builds APIs. Michelle really enjoys her job and has taken inspiration from her work building APIs in training Slash.

As you may know, an API is a collection of commands a user can give to a web service along with a set of responses that match the request. Michelle has trained Slash to do just the same.

Slash is a good boy, knows a variety of commands, and always responds correctly as long as you give him a request he's been taught. When he gets extra excited, his tail goes crazy — this isn't something Michelle taught him related to APIs, it's just because he's a lovable pup and really enjoys his training!

Step by Step Guide

1. Decide what API you need

What information are you looking for or do you want to change?

Are you trying to grab all of @dougthepug's Instagram posts? Maybe you want to automatically tweet at anyone who follows your dog's twitter (because even though dogs can't speak, they have a lot to say, we know Slash sure does).

If you already know the site or API you're trying to connect to, go directly to Step 2.

If you're trying to find data, but aren't sure where to start, Google is your friend. Search for "[stuff you're interested in] API" and see what comes up. You might be surprised how much information is out there.

If you'd like a simple example API, you can use the one Michelle made while training Slash. It has some of his favorite commands like retrieving balls and digging holes. We'll be using it throughout the rest of our examples.

2. Find the API docs

APIs provided by well-known companies should have thorough documentation on how to use them.

To find these, google "[Insert Company] API documentation" or "[Insert Company] developer".

The results should take you to the developer portal. Look for a link that says "Docs", "Documentation", "Reference" or "Technical Reference".

If the site provides both Documentation and Reference, the Reference section is what you're looking for, as it will provide specific details about the API and its endpoints. You might want to keep the Documentation section nearby, as it may have guides and other details about the service you're using.

Within the docs, you may need to look for the specific API you want as sometimes there can be many options. Facebook, for example, has separate APIs for marketing, ads, pages, and more.

If the API you want to connect to isn't well known (like Slash's) you may need to ask the developer for documentation. They may have a PDF containing the information you need or online documentation that is not listed on their website.

If you missed the link above, Slash's API docs can be found here.

3. Find the endpoint

API docs may look daunting, but once you know what to look for they're usually well structured and pretty standardized.

The first thing to look for is the appropriate endpoint(s). There should be one endpoint corresponding to each type of data you want. An endpoint could look like this: https://slashtheapidog.com/api/bones/{id} or just /bones.

The documentation should have a list of endpoints. They may be top level in the docs or under a section called "reference", "endpoints", or "methods".

To find the right endpoint, look for the name that corresponds with the data you're looking for. For example, if you want a list of all the holes Slash has dug, /holes is probably the right one. In any case, each endpoint should have a description to help explain what it does.

Slash the API Dog

From his docs, these are the endpoints in Slash's API related to holes:
GET https://slashtheapidog.com/api/holes
GET https://slashtheapidog.com/api/holes/{id}
POST https://slashtheapidog.com/api/holes
PUT https://slashtheapidog.com/api/holes/{id}
DELETE https://slashtheapidog.com/api/holes/{id}

4. Determine your request type

Now that you've found the right endpoint, you need to determine the type of request to send it.

There are 4 different types of requests:

GET
GET request is how you ask the API to respond with something that it has, most often data. You can ask for specific information about one item or a group of items based on the endpoint and parameters. This is the equivalent of asking Slash to bring you one of his bones or all of his bones.

POST
A POST request is how you tell the API to create something new. This is similar to asking Slash to dig (create) a new hole for you.

PUT
A PUT request is how you tell the API to update something that was previously created. This is similar to asking Slash to dig deeper (update) into the hole he dug.

DELETE
A DELETE request is how you tell the API to delete something that was previously created. This is similar to asking Slash to cover up (delete) a hole he previously dug.

Slash the API Dog

Think about these four types. Are you getting information, creating a new entry, changing an existing entry, or deleting one? That answer tells you exactly what request type you need.

5. Understand the parameters

Many requests require additional parameters. Parameters are the details of your request. For example, if you want Slash to bring you all the balls that are red, you need to specify the color. If you want him to create a new hole, you need to tell him where to put it and how deep to dig.

The API documentation you are referencing should have a section called "Parameters" or "Options" for each endpoint and request type. Pay attention to which parameters are required as some are optional. If a parameter is marked as optional, the docs may provide an example that is also the default.

Slash's API parameters might look something like this for retrieving balls:

GET https://slashtheapidog.com/api/balls

NameRequiredDescriptionExample
colorrequiredColor of the ballblue
squeaksrequiredWhether the ball is a squeaky toy or nottrue
sizeoptionalSize of the ball in centimeters, measured by diameter5
materialoptionalType of material used to make the ballrubber

6. Check for authentication

Most APIs require you to prove you have access to the API through some type of authentication. Slash wouldn't bring his bone collection to a stranger now would he?!

API documentation will typically have an entire section dedicated to authentication. It may be under a top-level link named "Authentication" or "OAuth" or could be hidden within sections like "Getting Started", "Guides", etc.

Look out for the following words when trying to find the authentication documentation: "Authentication", "Authorization", "OAuth", "Token", "Access", "Permissions".

There are many different kinds of authentication. Here's a brief overview of the most common types:

Basic Auth - Providing a username and password.API Key - Providing a unique key (like a complex password) given to you by the developer of the API.OAuth - A framework for allowing a third-party app to access another API on your behalf. When a separate company asks you to sign in with Google or Facebook credentials in a pop up window, this is usually OAuth.
If you're looking to access your own information, most likely you will use Basic or API Key authentication. If you are building an app that needs to access other people's data, you may need to set up OAuth, which is a bit more complicated than what we will cover here.

Assuming you're not setting up OAuth, you should determine whether you need basic authentication, an API key, or are accessing something that does not require authentication at all. Once you know the type of authentication, you can gather the information you need: username and password for basic or your API secret token, access token, or bearer token for API keys. Typically this information will be sent to the API in the headers, which is another way to send information in a request.

7. Format your request

We've got all the information we need! Now we just need to make the request and cross our fingers... But don't worry, with Slash's help you'll surely be headed for success.

Here are three different ways to connect to an API:

cURL - if you know how (and want) to code

cURL is a command line program that allows you to exchange data with APIs via the terminal on your Mac or Windows command prompt.

1. Mac users: Open the terminal (under Applications / Utilities). Windows users: Run the command prompt with admin rights or download curl if you are on an older version of Windows.

2. Try making a GET request with basic authentication by typing "curl -u <username>:<password> <url>", replacing anything in <> with the actual value. For example, Slash might access his list of bones like this:

curl -u slash:slashpwd https://slashtheapidog.com/api/bones

You should see the response from the API appear on the command line after you hit enter.

3. Try out some other types of requests:

GET request with API key authentication and parameters:
curl -H "Bearer: <key>" <url>?<param1>=<val1>&<param2>=<val2>
curl -H "Bearer: 125309h0ewgah" https://slashtheapidog.com/api/bones?age=2

POST / PUT request with parameters:
curl --data "<param1>=<val1>&<param2>=<val2>" <url>
curl --data "color=red&squeaks=true" https://slashtheapidog.com/api/balls

You can learn more about cURL by reading the full documentation.

Parabola - if you want to connect to and work with data without code

Parabola is a web app that allows you to easily connect to APIs and then work with the data through a visual, drag-and-drop tool.

Try out one of the example Parabola flows Slash built to work with his API:
GET Slash's List of Balls
GET Slash's First Ball
Add Slash's New Balls via POST
Update Slash's Bones Ages
DELETE Slash's Old Bones

1. Create a free account at https://parabola.io.
2. Create your first flow.
3. Find the API Import source and drag it onto your screen.

Parabola

4. Double-click the API Import to change its settings.

Parabola
Parabola

5. Enter the endpoint you want to use.
6. Change the authentication dropdown to the type you need and enter the details.
7. If there are any customizations you know you need to send (special headers, pagination values, etc.) you can add those as well.

Parabola

8. Hit "Update Settings" and Parabola will make the GET request! You should see the response data show up in the area to the right of the settings.

Parabola

You can now keep building in Parabola using this data or check out one of the other options for connecting to APIs. Parabola has an API Export step that will allow you to make PUT, POST, or DELETE requests. There are also several pre-built steps that allow you to easily connect popular APIs (like Google Sheets or Salesforce).

Postman - if you want to test API requests and don't need to do much with the data

Postman is an app for documenting and testing APIs.

1. Download postman here: https://www.getpostman.com/downloads/.
2. Create new request.

3. Pick the request type.

4. Enter your endpoint URL.

5. Pick the authorization type and enter the details you gathered.

6. Change the body to include your parameters.

7. Hit send!

8. Your response will show up in the Response section at the bottom.

8. Understand your response

Now that you've made a request we can take a look at the response, it probably looks something like this:

or this:

or if you used Parabola, this:

Parabola

Most APIs will return JSON like the top example, but some may return XML. Parabola will return the data in a familiar table format.

Hopefully the response you received looks a lot like the above in the sense that you got data back! You can read that data by looking at each key and its value.

Some things to look out for in your response:

Pagination information

Slash may only have dug enough holes to return one page of API results, but yours may have many more.

Parabola and Postman have pagination support, but if you need to learn more about it for your specific use case look for the words "page", "cursor", "offset", or "limit". Those are all related to pagination and the API documentation should have some information on how to use them to get to the next page.

Errors

You may have received something that doesn't look like the data you were expecting and resembles an error message.

This means that something went wrong with your request. Most errors will give you some information about what happened so you can make changes to the request. Errors will also be accompanied by a status code in the 400 to 599 range. Learn more about status codes and what they mean here.

9. Use the data

Congrats on making a successful request and receiving a response. Slash is so proud of you!

Slash the API Dog

Now that you have some data (GET) or have been able to make the API take an action (POST, PUT, or DELETE) you will likely want to do something with the data or power. The true power of APIs comes from the way that you work with them.

Being able to ask Slash to fetch a bone for us once is great and we certainly want to play with him. But imagine Slash has hundreds of bones and our goal is to safely bury and log all of his bones. To do that efficiently, we'd need to chain actions together.

We would ask him to GET a bone to us, POST a new hole the same size as his bone, PUT the bone into the hole, GET the coordinates of that hole, and finally POST those coordinates to a tracking doc somewhere so we can have our list of tracked bones in their holes.

What we've done here is chained a set of actions together to create a flow. This is just one example, but hopefully you can start to understand the impact of being able to programmatically work with APIs to build more complex flows of actions and data. This can be done in a programming language if you're familiar with (and want to) code or created using a tool like Parabola that allows you to visually drag and drop steps to connect to APIs and work with that data.

API Terms

Endpoint

An endpoint is one single URL that you can make a request to. Each endpoint will usually be responsible for covering the interaction of a single or group of items.

For example: https://slashtheapidog.com/api/bones is one endpoint and https://slashtheapidog.com/api/balls is another endpoint.

Request

An API request is just like a request you might make to Slash the dog. You can request Slash to "bring you the green ball" and you can request an API to "GET you the data at a specific endpoint".

Because Slash is so well trained, every time you ask him to bring you the ball, he'll bring you the exact same green ball (with the exact same amount of slobber) without making any changes to it. This is just like an API, as long as your request is defined correctly, it'll do exactly as you request: in this instance GETting you the specific data you requested.

Response

The response is what you get back from Slash or the API after making the request. Slash is smart and so he'll always give you back a response, whether it's fulfilling your request (such as bringing you the green ball) or barking to let you know he doesn't understand your request—both are valid responses.

APIs will send responses to requests just like Slash does. Responses will almost always be very clear and include a status along with a message or data about the result of the action taken.

There are a few common responses:

Your request was good and the action you requested was taken. This usually results in a 200 status and data or a message about the action taken. This is the equivalent of Slash bringing you the ball you asked for.
Your request was bad and the API didn't understand how to take the action you requested. This usually results in a 400 status and a message about what was wrong. This is the equivalent of Slash barking at you because you're not making any sense.
Your request may have been good, but the API is not working for some reason. This will usually result in a 500 status. This is the equivalent of Slash taking a nap because he's tired, so he can't bring you the ball right now.

Slash the API Dog

Parameters

Parameters give extra information to an API during a request to help clarify the request.

When you are giving Slash requests, you need to give him parameters so that he knows how to do exactly what you are asking. For instance, rather than just asking him to bring you a ball, you could ask him to bring you a yellow ball.

An API is exactly the same, you might make a GET request to the endpoint https://slashtheapidog.com/api/ball and provide a parameter to specify that you want the color of the ball to be yellow. Parameters can be added to the endpoint like https://slashtheapidog.com/api/ball/yellow or https://slashtheapidog.com/api/ball?color=yellow.

The way you specify parameters is important and will vary based on the API, so it's important to look at the API docs to make sure you give them in the right way.

Headers

Headers are similar to parameters in that they are another way of giving extra information to an API. It's common for headers to be used as a way of specifying authentication. Headers are used by both the request and the response. They may also include technical information relating to the request or response, such as how big it is and how long the information is valid for.

In most cases, beyond adding authentication headers, you won't need to worry about the headers.

Rate Limiting

Rate limits define how many requests you can make to an API in a given period of time. These will vary per API and you should check the API docs to understand the limits.

For instance, if you ask Slash to bring you the yellow ball 100 times in 1 minute, he sure will try his hardest, but he probably won't be able to fulfill all of your requests because it's just too many in a short period of time and at the end of that minute, he's going to be darn tired! It'd be better if Slash could just tell you ahead of time, that he can only fetch the ball 10 times per minute at most.

APIs implement rate limits for the same reason, so that they give you a good understanding of maximum usage limits and they can appropriately tell you when you've sent too many requests in a given period of time. APIs will usually respond with the 429 status code, whereas Slash may just ignore your extra requests or start barking.

Authentication

Authentication is how you tell the API who you are in a secure method when making the request. This allows the API to determine if it should fulfill your request and tailor the request specifically to you.

For instance, Slash will only dig new holes in the backyard when his owner, Michelle, asks him. If anyone else does, he won't do it because he knows only Michelle has the authority to have her backyard dug up. Michelle authenticates her commands with Slash by her appearance, smell, and voice, so he knows he can trust a command is coming from her and no one else.

APIs behave the same way, but need another way to specify that you are who you say you are. There are many different ways to authenticate, but most commonly it means providing some sort of API Key in your request. You should check the API docs for exactly how to authenticate a given API.

Response Formats

JSON

JSON is a format for structured data. It's currently considered the standard for modern APIs, as such most APIs respond with their data in a JSON format. Here's a quick snippet of JSON formatted data.

Reading JSON on its own can be a bit tricky, but there are a number of sites online to help parse it and software tools that interact with APIs may also be helpful in parsing JSON.

If you use Parabola to make your requests, as discussed in the step by step guide, the JSON will be automatically parsed in a table format.

XML

XML is a format for data and information. If you're familiar with HTML, the style will look pretty similar. XML is an older format of data and is generally used by older APIs. XML is less structured and rigid than JSON, the same data can be displayed in multiple ways, which can make it tougher to understand.

Like JSON, software tools, like Parabola, that interact with APIs may be helpful in parsing it into a more readable format.