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 is Michelle's adorable, lovable dog (pictured above). 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 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.

Step 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".

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 in the previous step, Slash's API docs can be found here.

Step 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.

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}

POST https://slashtheapidog.com/api/holes/{id}

Step 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

A 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.

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.

Step 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

Step 6: Format Your Request

We’ve got all the information we need, now we just need to make the request!

Here are two different ways to connect to an API that require no code. Let’s connect to Slash’s API to get his list of balls by making a GET request to https://slashtheapidog.com/api/balls

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.

Check out the example Parabola flow Slash built to work with his API: GET Slash’s List of Balls.

Create a free account at https://parabola.io.
Create your first flow.
Find the API Import source and drag it onto your screen.
Double-click the API Import to change its settings.
Enter the endpoint you want to use, in this case: https://slashtheapidog.com/api/balls
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.

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.

Download postman: https://www.getpostman.com/downloads/.
Create new request.
Pick the request type, in this case: GET.
Enter your endpoint URL, in this case: https://slashtheapidog.com/api/balls
Hit Send.
Your response will show up in the Response section at the bottom.

Step 7: Use the Data

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. 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.

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 chains of actions and data. This can be done in code or using a tool like the ones described above.

Hope you found this guide helpful as an intro to working with APIs without any code. I’m excited to see what you build. If you’ve got a minute, tweet at me or reply here and let me know!

Step 8: Final Notes

The full version of the step by step guide above lives at WorkWithAPIs.com — check it out there for a more detailed walk-through as well was important API terminology you should know.

Introduction: Connect to APIs Without Code