How Do APIs Work?

Overview

For an API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. (application programming interface) call to succeed, you need to build out the API request with specific information. Depending on the call you make, you might have to include various parameters. Let’s explore how to make an API request.

What You'll Learn

In this article, you’ll learn about making API calls and troubleshooting API responses.

How to Make an API Call

Making an API call is similar to navigating an automated telephone system. Once you connect to the system, you must tell it what information you want to receive. So, you must convey your request before the system provides you with the information you seek.

Most API calls contain three pieces of information:

  • HTTP Request Method

  • Path Parameters

  • Payload

The flow of information looks something like this:

A static image displaying a typical API call process.

HTTP Request Method

Each API contains an HTTP HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML. (Hypertext Transfer Protocol) method. The HTTP method is the API’s way of stating its intended action. 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 are the most common examples:

  • GET: Retrieves and reads existing resources.

  • POST: Creates new resources.

  • PUT: Updates existing resources.

  • DELETE: Deletes a resource.

Path Parameters

To make a successful call, your API must contain the appropriate HTTP method. Depending on the method, you might need to include other parameters, like path or query parameters.

For example, let's create a GET call using Unqork's internal GET Module Submissions API. For a GET call, you need two pieces of information:

1. HTTP Request Method
2. Path Parameter

For a GET API call to work, you must specify the GET HTTP method. You also must provide the server URL A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address. where you're trying to retrieve the information. The GET Module Submissions API lets you retrieve submission data for a specified module. So, the URL must contain the module ID for that specified module. The necessary URL to retrieve module submission data looks like the following: https://{subdomain}.unqork.io/api/1.0/modules/{moduleId}/submissions.

There are two path parameters in the URL that require specific information:

  • {subdomain}: Replace this portion of the URL with your environment subdomain. For example, training-staging is the subdomain for the https://training-staging.unqork.io environment.

  • {moduleId}: The module ID for the specific module where you want to retrieve information.

When using the Plug-In component's GET Module Submissions API, you can select the module you want and the path parameters automatically populate.

Payload

All APIs need at least the HTTP method and the resource URL. But often, you'll 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.

For example, let's look at Unqork's internal Create Module Submission(s) API. Because this API call creates new module submissions, it's a POST HTTP method. But it's not enough to tell the server this is a POST call and to provide the URL to the module where you want to create the submission. We must also include the actual data to store in the submission.

TIP  For more information about the necessary payload for the Create Module Submissions API, see our API documentation: https://developers.unqork.io/#operation/createModuleSubmissions.

How to Recognize and Troubleshoot API Responses

Whenever you make an API request, a response is returned. But that response might not always be as simple as Success or Failure. Depending if the request was successful or not, you can get a response containing a variety of response codes.

Once the server performs the requested action, it sends a response back to the browser. Responses show in the DevTools Console The DevTools Console helps you securely store, build, test, and deploy your software. when you inspect your module. 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.

TIP  To learn more about using the DevTools Console, view our Access Submission Data Using the DevTools Console article.

There are five different status code categories:

Status Code

Description

1xx (Informational)

The request was received and is processing.

2xx (Success)

The request was received and accepted.

3xx (Redirection)

Further action to proceed.

4xx (Client Error)

An error has occurred  on your end.

5xx (Server Error)

An error has occurred on the server's end.

You don't always receive Informational and Redirection status codes. Informational codes provide a status and don't require any action on your end. Redirection codes indicate that a request has more than one possible response. In most cases, you have to choose a response in setup to continue the request.

Success, Client Error, and Server Error status codes as the most common. Let's our Get Module Submissions and Create Module Submission(s) examples to explain what status codes to expect.

Success Responses

In the Get Module Submissions call, you're requesting 50 submissions from the module whose module ID is specified in your URL. If your call is successful, you'll see those 50 submissions returned. You'll also see an HTTP status of 200 - OK.

In the Create Module Submission(s) call, you're creating a new submission. If this is request is successful, you'll see a 201 - Created response. You'll also see information about the new submission, including the submission ID and the module ID storing the submission.

Error Responses

If your call is not successful, you’ll see an error response in the DevTools Console. Here are a few error responses you might encounter, along with tips to fix them:

Error Code

Description

Notes

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.

Ensure 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 correct API call method you and that you’re sending it to the correct location.

500

An error occurred on server-side.

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

TIP  For more information on HTTP status codes, view our HTTP Status Codes article.