How Do APIs Work?

Overview

For an API (application programming interface) call to succeed, you need to build out your request with certain information. Depending on the call you try to make, you must include different parameters. Let’s take a closer look.

What You'll Learn

In this article, you’ll learn:

How to Make an API Call

Making an API call is a bit like navigating an automated telephone system. Once you connect to the system, you must tell it what you’re looking for. In other words, you must convey your request before the menu can give you the information you seek. An API works the same way.

Most API calls contain three things:

  • HTTP Request Method

  • Path Parameters

  • Payload

The flow of information looks something like this:

HTTP Request Method

Each API contains an HTTP (Hypertext Transfer Protocol) method. You can view an HTTP method as the API’s way of stating its intended action. So, each HTTP method also has an associated verb describing what it does. For example, if you use an API to retrieve data, your API is making a GET call. Here's a look at some other common examples:

  • POST: Creates new resources.

  • GET: Reads existing resources.

  • PUT: Updates existing resources.

  • DELETE: Deletes a resource.

Path Parameters

To make a successful call, your API must contain the appropriate HTTP method. But depending on the method, you might need to include other parameters. These parameters are either path parameters or query parameters.

Let's take a closer look at making a GET call. We'll use the example of the Get Module Submissions API within Unqork.

For this API to work, you'll specify the HTTP method (GET). But on top of that, you'll also provide the server URL that you're trying to GET from. That URL looks like this:

https://{subdomain}.unqork.io/api/1.0/modules/{moduleId}/submissions.

Note that {subdomain} represents the environment you're working in. And {moduleID} represents the module holding the data that you're trying to GET. The {subdomain} and {moduleId} are both path parameters. Unqork automatically provides URLs for internal APIs with placeholder text as above.

Payload

All APIs need at least the HTTP method and the resource URL. But you'll often also need to send more information for the server to understand your request. We refer to this extra information as a payload. A payload includes any data sent between the client and the server.

Let's look at another Unqork example: Create Module Submission(s). We know this is a POST call because we're creating new resources from a module submission. But it's not enough to tell the server this is a POST call and to provide the URL where we want to create the submission. We must also include the actual data to store in the submission. You'll do this using the same JSON format as the request body.

The parameters required for each API vary. You can find more about each API call by going to developers.unqork.io.

How to Recognize and Troubleshoot API Responses

Whenever you make an API call, you'll get a response. But that response might not always be as simple as Success or Failure. Let's take a look at how you can interpret a response to get some meaning from it.

Responses show in the console view when you inspect your module. Once the server performs the requested action, it sends a response back to the browser. The first thing you'll see in an API response is an HTTP status code. This status code tells you how the server handled your request. There are 5 different status code categories:

Status Code

Description

1xx Informational

Shows that your request was received and that the process is continuing.

2xx Success

Shows that your request was received and accepted.

3xx Redirection

Shows that you must take further action to proceed.

4xx Client Error

Shows that an error has occurred and that it originated on your end.

5xx Server Error

Shows that an error has occurred and that it originated on the server's end.

You don't always receive Informational and Redirection status codes. There are a few reasons for this. Informational responses aren't all that useful as they don't call for any action on your end. And Redirection codes are only necessary if you need to provide more information. In most cases, you'll have provided all information at the start.

That leaves Success, Client Error, and Server Error status codes as the most common. Let's see what those look like in our Get Module Submissions and Create Module Submission(s) examples.

Success Responses

In the Get Module Submissions call, you're requesting 50 submissions from the module specified in your URL. If your call is successful, you'll see those 50 submissions returned. If that's not enough sign of success, you'll also see an HTTP status of 200 OK. Again, this lets you know that your call is successful.

In the Create Module Submission(s) call, you're creating a new submission. So, if this is a success, you'll see a 201 Created response. You'll also see information about the new submission. This information includes a submission ID and the module ID where you can find the submission later.

Error Responses

If your call is not successful, you’ll see an error response when inspecting the page. Here are a few error responses you might encounter as well as some tips on how to fix them:

Error Code

What It Means

How to Fix It

401

You don’t have authorization to view the data that you requested.

Check with your service provider to verify that your access is valid.

404

The server can’t find the resource that you referenced.

Check what you entered in the URL, ensuring your subdomain and module ID are correct.

405

The resource that you’re referencing doesn’t accept the API call method that you’re trying to make. (For example, making a GET call to a resource that only accepts POST calls.)

Check that you’re using the API call method you intended and that you’re sending it to the correct location.

500

An error occurred on the server-side. Usually, you won’t get any more detail.

Clear your browser’s cache and try again. If the call fails again, contact the API provider for more information.