Getting Started with APIs: Understanding an API Request URL

Vineet Antil

September 4, 2020

Application programming interfaces (APIs) are everywhere. They’ve become essential building blocks for modern software and are used by any organization that has a digital presence. That means that anyone using the internet today is experiencing APIs.

When you’re shopping online and adding things to your digital cart, there is a lot going on behind the scenes: frontend systems are talking to the backend systems via APIs, checking for inventory, showing availability, estimating delivery times, etc.—all while you’re browsing the app. This can seem very technical to people with non-coding backgrounds, so this blog post is meant to simplify things for the API beginner. After reading this introductory piece, check out the Intro to Postman: Sending a Request video to keep learning about API requests.

But first, what is an API? APIs essentially help two systems of software or applications talk to each other. One application sends a  request and is known as the API client, while the other application sends a response. This request interaction is the foundation of APIs.

There are many kinds of requests that can be sent over the internet. You can retrieve some data with GET requests, add data with POST requests, replace data with PUT requests, or create custom request types. Fun fact: Postman has powered more than 1 billion API requests. You can dive deeper into request methods here.

Related: What are the components of an API?

An example of a request URL

Let’s take one GET request URL example and talk about its various parts. This example will help you understand what’s going on when you send a request.

We’re going to use a request URL from one of the APIs of a familiar service that most of us use in our daily lives—Google Maps. The Google Maps Geocoding API lets you send a request with an address and returns the geo-coordinates for the address. We will use this API to get the coordinates of the iconic Golden Gate Bridge near Postman’s San Francisco office.

If we use the Google Maps Geocoding API to get coordinates for a corresponding address (Golden Gate Bridge), the URL would look something like this:
https://maps.googleapis.com/maps/api/geocode/json?address=Golden+Gate+Bridge,+CA&key=YOUR_API_KEY

Now we’re going to break down five components of this URL

1. The base URL (in bold below) tells your browser or app the location of the API where the request is being sent. It is the endpoint where the request goes to be processed according to the rest of the string in the request URL: <strong>https://maps.googleapis.com/maps/api/geocode/</strong>json?address=Golden+Gate+Bridge,+CA&key=YOUR_API_KEY
2. There are several data formats that can be used when sending requests. It’s important to note that the request specifies the data format so that the systems talking to each other can understand the request. In this example, JSON is the data format in which the request is being sent: https://maps.googleapis.com/maps/api/geocode/<strong>json</strong>?address=Golden+Gate+Bridge,+CA&key=YOUR_API_KEY

3. To get the coordinates of Golden Gate Bridge we need to send address as a part of the request. This address is sent as a query in the request. These queried items are called parameters. Parameters are mentioned after the ? in the URL. If there is more than one parameter being sent as a query, they are appended with & in the request: https://maps.googleapis.com/maps/api/geocode/json<strong>?</strong>address=Golden+Gate+Bridge,+CA<strong>&</strong>key=YOUR_API_KEY

4. In the above URL there are two parameters being passed: address and key. These parameters are also sent as a key-value pair. The section of the URL that says address=Golden+Gate+Bridge is called a key-value pair. address is the key and Golden+Gate+Bridge is the paired value.
5. There is another key-value pair at the end of the URL: key=YOUR_API_KEY. This is a very important aspect of this request URL. When you send a request to a server (in this case it’s the server of the Google Maps Geocoding API), the server needs to authorize that request. It does so by checking YOUR_API_KEY. Once the authorization is done, the server can share the response. These keys can be obtained from the developer portal or website of the API provider. Again, here’s the link for the Google Maps Geocoding API.

Now that you understand what an API request is and what to look for in a request URL, go ahead and watch the video Intro to Postman: Sending a Request, which will further help you create a request in Postman and start working with APIs.