Beginner's Guide to Working with APIs

Previously in Introduction to APIs we discussed how APIs are constructs made available in programming languages to allow developers to create complex functionality with ease. Now that we have a clear understanding on APIs, let's explore how to work with them.

Last time, we made the following request:

# Defining method (X), and headers (H):
cURL -X GET 'https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY' -H 'Host: api.nasa.gov' -H 'Accept: text/html,application/xhtml+xml,application/xml'

# Or, alternatively can also be written verbose

# Using long form options
# Splitting cURL commands across multiple lines
# Line continuation character is represented in cURL by `\`

cURL \
--request GET 'https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY' \
--header 'Host: api.nasa.gov' \
--header 'Accept: text/html,application/xhtml+xml,application/xml'

Notice that the code above isn't JavaScript, and it looks different from the one from our previous example. It starts with cURL (for client URL), which is a command line tool that developers use to transfer data.

Bottom line, get familiar with cURL. At the most fundamental level, cURL lets you (a) talk to a server, (b) it supports several different protocols and (c) runs on multiple platforms. All of this makes cURL ideal for testing communication from anywhere that has access to a command line and network connectivity. More on what cURL does here, and more on cURL's documentation here.

cURL Tooling

What are the tools we are able to use to test different web services before creating any API Integrations? The ones I would recommend and that we'll be using today are:

• Postman: for testing web services and generating cURL snippets (and for several other languages).
• cURL Converter (optional): to convert cURL commands to JavaScript (and for several other languages).

So this time around, let's start using cURL to represent the API calls we'll be working with using Postman (an API platform for building and using APIs).

Using Postman

Sending your first request

Postman makes it easy to create and send API requests. You don't need to enter commands in a terminal or write any code. From its GUI, it is as simple as creating a new request (using the data from a cURL snippet, for example) and clicking on Send. The API response appears right inside of Postman.

If you have never used Postman before, let's do this step by step.

How to sign in Postman:

1. Sign in with Google (or email/username) in Postman
2. Fill out your user information (name and role, John Doe, Fullstack Developer)
3. Continue without a team

Creating an HTTP Request using cURL and Postman

So let's grab our cURL snippet and import it into Postman. In order to do this:

1. From your personal workspace, click on the + icon New HTTP Request to send a request right away. Alternatively, use the Import tool and paste the cURL snippet provided above to save some time,
2. If you are importing (if not skip this step), a modal/pop-up will show up, where you will import your API specifications as Raw Text, click Continue and confirm by clicking Import.
3. Click on Send, and
4. Review the Response right inside of Postman.

Note: Importing an API is a great feature that allows us to import an existing API schema from a local file, directory, URL, raw text, a code repository, or even an API gateway. This is useful to know because Postman allows you to import and export data to help you consolidate your API development workflow.

Before we dive into understanding what's involved here, let's review HTTP more in depth.

HTTP Request Methods

As we already discussed, REST architectural style uses all the advantages of HTTP, so in turn, any RESTful API would also inherit these. At the most basic level, an API request includes the URL for its resource endpoint and its HTTP request method. An HTTP Request Method (also referred to as HTTP verbs) indicates the desired action you want to perform for a given resource.

All HTTP request methods share the same common features: they are safe, idempotent, and cacheable. Let's review the most common methods:

• GET retrieves data from an API
• POST sends new data to an API
• PATCH and PUT updates existing data
• DELETE removes existing data

Let's explore these HTTP Methods using our first Postman Collection.

Postman Collections

These are a group of saved requests. The more you use Postman, it can be time-consuming to leave tabs open for request, to be looking for them in your history section, or to be re-creating them from scratch. Instead, you can save all your requests, organize them and share them as a Postman Collection.

You can either create a collection by:

• Saving a single request and using the New Collection quick link from the pop-up/modal OR by
• Clicking the + icon from your workspace's Overview tab (left-side menu)

Now that you know how to create a Postman Collection, let's quickly discuss how to share your Postman work.

Exporting Postman data

You can export your Postman Collections as JSON files for later use from any Postman instance or use them with a CLI tool like Newman (a tool that allows you to run Postman collections from the command-line). Click on Export or Share anywhere in your collection folder. From there, you have the following options:

• Send your collection via Email for collaboration (similar to the previous export option)
• Export as a JSON file
• Via JSON link, which generates a static snapshot of your collection (like the one I provided before).

Conclusion

Postman has over 135K published collections that you are able to fork to explore several different APIs. Companies are actively using Postman not only to develop and test their APIs, but also to quickly create a solid base for documentation and to share them with the world. There are AI, Communication, Data Analytics, Developer Productivity, DevOps, Financial Services categories for all of Postman's public collections so make sure to check them out and keep learning how to work with APIs along the way.

NOTE: This article belongs to an ongoing series which is still a work in progress. If you haven't already, check out Part 1: Introduction to APIs. Part 3: Beginner's Guide in Testing APIs.

Thanks for reading.