When testing endpoints with various parameters, you have the option to utilize one of the many GUI REST clients available for making requests. By "GUI," I refer to a graphical user interface that includes interactive elements such as boxes and buttons for easy navigation and operation. While you can also use curl（which is covered in detail in my article "Understand cURL More in Just 10 Minutes!"） GUI clients generally make testing with REST APIs more straightforward and user-friendly.
✨ Contents
- What is an API request?
- Why use a GUI client?
- Popular API GUI clients
- Activity: Make requests with Apidog
- Other REST clients
- Enter several requests for the Aeris API into Apidog
What is an API request❓
An API request is a message sent by an app to the API asking for a specific service, functionality, or data.
An API request, or an API call, is a message sent by an app to the API (application programming interface) asking for a specific service, functionality, or data. An API request is the first step in exchanging data or functionality through an API. Whenever an app wants to access a feature or data from an outside system using an API, it initiates an API request. API requests work together with API responses to enable applications to share data and provide seamless user experiences.
Once an app creates an API request, it sends the request to the API server using the appropriate communication protocol, such as HTTP (Hypertext Transfer Protocol). The API server receives the request, processes it, and generates the corresponding API response.
Elements included in an API request
- Endpoint: The API endpoint is a unique URL that acts as the target for the API request. This URL corresponds with the location of the requested resource and directs the API request to completion.
- Request method: Also known as the HTTP method, the request method specifies the type of action to be performed on the resource being requested from among the following functions:
- GET: Retrieve data from the server
- POST: Submit data to the server for processing or creation of a new resource
- PUT: Update or replace an existing resource on the server
- DELETE: Remove or delete a resource from the server
- Headers: Headers contain additional information or metadata about the request, such as authentication credentials, content type, caching directives, and other API specifics.
- Parameters: Depending on the API design, the request may include parameters (or a payload) that provide additional information needed to execute the requested action.
- Body: In the case of PUT and POST requests that involve creating or updating data, the request body will specify the appropriate data format, such as JSON (JavaScript Object Notation) or XML (Extensible Markup Language).
- Authentication: To ensure security, an API request may include authentication credentials — an API key, access token, or username/password combination — to validate the identity and permissions of the requesting application.
- Response: After receiving an API request, the API processes it and sends back an API response, including the requested data and a confirmation or error message if the request fails.
Why use a GUI client❓
With a GUI REST client, you can:
-
Save your requests (and numerous variations) in a way that’s easy to run again
- More easily enter information in the right format
- See the response in a prettified JSON view or a raw format
- Easily include header information
With a GUI REST client, you won’t have to worry about getting curl syntax right and analyzing requests and responses from the command line.
Popular GUI clients
Some popular GUI clients include the following:
Of the various GUI clients available, Apidog is a good choice, since its user-friendly design and powerful features. Its visual-first approach simplifies complex API interactions, is free, and is easy to configure.
🔥Activity: Make requests with Apidog
In this exercise, you’ll use Apidog to make a request using OpenWeatherMap’s current weather data API endpoint. To make the request:
If you haven’t already done so, download and install the Apidog app at https://apidog.com/download/. (You can also use the web version.)
Start the Apidog app and sign in when prompted.
Click the + tab to create a new request. Insert the following endpoint into the box next to GET:
https://api.openweathermap.org/data/2.5/weatherClick the Params tab (below the box where you inserted the endpoint) and then add the following three parameters in the Name and value rows:
- key:
zip/ value:95050 - key:
units/ value:imperial - key:
appid/ value:
For the value for appid, use your own API key (- Log in https://home.openweathermap.org/api_keys and register to get api keys). Your Apidog UI should look like this:
When you add these parameters, they appear as a query string to the endpoint URL in the GET box. For example, your endpoint will now look like this: https://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&appid=APIKEY (but with different query string values and with your own API key instead of APIKEY). Query string parameters appear after the question mark ? symbol and are separated by ampersands &. The order of query string parameters doesn’t matter.
Note that many APIs pass the API key in the header rather than as a query string parameter in the request URL. (If that were the case, you would click the Headers tab and insert the required key-value pairs in the header. But OpenWeatherMap passes the API key as a query string parameter.)
- Click Send.
The response appears in the lower pane. For example:
Save the request
In Apidog, click the Save button (above Send). The Save Request dialog box appears.
In the Save Request box, type a friendly name for the request, such as “OpenWeatherMap Current API.”
Click New Collection to create a folder to save the request in. Name your new collection (e.g., “OpenWeatherMap”) and click the orange check mark. Then select the new collection you just created.
After you create the collection, the Save button will be enabled. Your Apidog collection should look something like this:
4.Click Save.
Saved requests appear in the left side pane on the Collections tab.
🔥(Example) Make a request for the OpenWeatherMap 5 day forecast
Now instead of getting the current weather, let’s use another OpenWeatherMap endpoint to get the forecast. Enter details into Postman for the 5 day forecast request. In Postman, you can click a new tab, or click the arrow next to Save and choose Save As. Then choose your collection and request name.
A sample endpoint for the 5 day forecast, which specifies location by zip code, looks like this:
https://api.openweathermap.org/data/2.5/forecast?zip=95050,us
Add in the query parameters for the API key and units:
https://api.openweathermap.org/data/2.5/forecast?zip=95050&appid=APIKEY&units=imperial
(In the above code, replace APIKEY with your own API key.)
Observe how the response contains a list that provides the forecast details for five days.
🔥(Example)Make one more OpenWeatherMap API request
Make one more OpenWeatherMap API request, this time changing the way you specify the location. Instead of specifying the location by zip code, specify the location using lat and lon geocoordinates instead. For example:
https://api.openweathermap.org/data/2.5/weather?lat=37.3565982&lon=-121.9689848&units=imperial&appid=APIKEY
(In the above code, replace APIKEY with your actual API key.)
Apidog has a lot of other functionality you can use.
Other REST clients
Although Apidog is a popular REST client, you can also use others, such as Insomnia, RapidAPI for Mac, and Hoppscotch.
🔥Enter several requests for the Aeris API into Postman
Now let’s switch APIs a bit and see some weather information from the Aeris Weather API, which you explored a bit in Scenarios for using a weather API. Constructing the endpoints for the Aeris Weather API is a bit more complicated since there are many different queries, filters, and other parameters you can use to configure the endpoint.
Here are a few pre-configured requests to configure for Aeris. You can paste the requests directly into the URL request box in Postman (after customizing the CLIENTID AND CLIENTSECRET values), and the parameters will auto-populate in the parameter fields.
When you make the following requests, insert your own values for the
CLIENTIDandCLIENTSECRET(get API key for the OpenWeatherMap API).
Get the weather forecast for your area using the observations endpoint:
http://api.aerisapi.com/observations/Santa+Clara,CA?client_id=CLIENTID&client_secret=CLIENTSECRET&limit=1
Get the weather from a city on the equator — Chimborazo, Ecuador using the same observations endpoint:
http://api.aerisapi.com/observations/Chimborazo,Ecuador?client_id=CLIENTID&client_secret=CLIENTSECRET&limit=1
Find out if all the country music in Knoxville, Tennessee is giving people migraines using the indices endpoint:
http://api.aerisapi.com/indices/migraine/Knoxville,TN?client_id=CLIENTID&client_secret=CLIENTSECRET
You’re thinking of moving to Arizona, but you want to find a place that’s cool. Use the normals endpoint:
http://api.aerisapi.com/normals/flagstaff,az?client_id=CLIENTID&client_secret=CLIENTSECRET&limit=5&filter=hassnow
By looking at these two different weather APIs, you can see some differences in the way the information is called and returned. However, fundamentally both APIs have endpoints that you can configure with parameters. When you make requests with the endpoints, you get responses that contain information, often in JSON format. This is the core of how REST APIs work — you send a request and get a response.
With Apidog, simplifies API development and testing.
Top comments (6)
API newbie here! For those like me who are having a hard time grasping the ins and outs of the UI, It really helped me understand the concepts in these chapters better and absorb the information a lot faster.
Thank you for this great course! I noticed something while doing the activities listed in this module. The sentence "The query string is the code followed by the ? in the endpoint URI." implies that the "?" comes after the query string. Isn't the reverse true?
No, the reverse isn't true. any parameters that appear before the "?" are called path parameters and their order is not interchangeable, nor are they optional.
Great！
This tutorial is fantastic! I love the hands on aspect.
Thanks a lot. I'm glad that you liked this 💯