Understanding API Documentation and Specifications

Overview

Let's dive into the details of API (application programming interface) calls. We'll start by exploring API documentation. Then, we'll talk about the importance of building API modules using API specifications. API documentation and specifications are the keys to understanding all your API integrations.

What You'll Learn

In this article, you'll learn:

• About API documentation.

• About the expected information in API documentation.

• About API Specifications.

What Is API Documentation?

To fully understand your API calls, you must understand their documentation. API documentation should explain:

• What the API call does.

• The type of data you'll get from the API call.

• How to connect the API call.

API documentation should also have examples of parameters, requests, and responses for each call. You may even see the call's rate limits. This is the number of API requests you can make in a specified amount of time.

Expected Information in API Documentation

The following information applies to all API calls—not just Unqork API calls. Here we'll explore how both internal and external API documentation works. Most external services have publicly accessible API documentation. You'll find that API documentation is available with a quick search. For instance, you can search DocuSign API Documentation or SendGrid API Documentation. This documentation will ensure you set up your API calls correctly.

You'll find that most API documentation includes the following sections:

• API endpoints

• Path parameters

• Query parameters

• API request body

Let's look at each section in more detail.

API Endpoints

First, let’s talk about API endpoints. Each API associates with a URL. At the end of each URL is the specific data point of your API call. This data point is the endpoint. Endpoints are how you connect API calls. The format of the endpoint depends on its part of an external or internal API call. Let's look at both.

External API Endpoints

Let's look at a couple examples of external API calls. Here's the base URL for an external Unqork API call:

• Base External API URL: https://{yourSubdomain}.unqork.io/api/1.0/

All Unqork API calls that use external services include this URL. But this URL isn't enough to run a successful API call. You also need an endpoint where you'll retrieve specific information. This is how your API URL will look, with the endpoint in bold:

• Full External API URL: https://{yourSubdomain}.unqork.io/api/1.0/modules/{moduleId}/submissions

Where you see {yourSubdomain} and {moduleId}, you'll add the appropriate information.

Internal API Endpoints

To make internal Unqork calls, you'll use a Plug-In component. When configured, the Data Source URL populates with the following base format: /fbu/uapi/.

So, this is how an internal API URL will look, with the endpoint in bold:

• Full Internal API URL: /fbu/uapi/modules/{moduleId}/submissions

Again, where you see {moduleId}, you'll add the appropriate information.

Path Parameters

API documentation also provides you with the path parameter of the API call. The path parameter is the location of the information you want from the API response. You'll find your path parameter inside your API endpoint.

Let's revisit the previous full external API URL example: https://{yourSubdomain}.unqork.io/api/1.0/modules/{moduleId}/submissions. The path parameter of this API URL is moduleId.

Query Parameters

Now that you've found the information you want using your path parameter, let's filter it. You'll use query parameters to do this. You'll find query parameters at the end of your API URL. They are also easy to spot because they begin with a question mark (?). After the question mark, you'll find the 2 parts of the query parameter:

• Parameter Name: This is the filter of the query parameter. You'll see it displayed as a formula with an equal sign. For instance, you could sort by a specific value: ?sortBy={parameter value}.

• Parameter Value: This is the specific value you want to filter. The type of value depends on the parameter. For example, it could be a number, a string, or a mathematical expression.

When adding more than one query parameter, you'll need to separate each with an ampersand (&).

Let's look at the full external API URL example again: https://{yourSubdomain}.unqork.io/api/1.0/modules/{moduleId}/submissions. Now, let's add a couple of query parameters. Remember, query parameters must start with a question mark. And, where you have more than one query parameter, an ampersand should separate them. Here's an example, with 2 query parameters in bold:

https://{yourSubdomain}.unqork.io/api/1.0/modules/{moduleId}/submissions?sortBy=modified&sortOrder=-1

API Request Body

When using POST or PUT API calls, you'll typically send a request body. So, there must be information relating to your API request body in the documentation. API documentation should include:

• The format of the request body. This could be JSON or XML.

• The keys of the request body.

• An example of how the request body might look.

• An example of a successful and unsuccessful API response.

What are API Specifications?

API specifications explain how the API call functions and what to expect when using it. They also show how API calls link together. More than that, API specifications include the design philosophy of your API call.

These are the standard specifications inside and outside of Unqork:

• External: OpenAPI Specification

• Internal: Unqork's API Specification snippet

Let's look at each in more detail.

OpenAPI Specification

The standard for API design is the OpenAPI Specification description format. You'll find a link to the OpenAPI Specification here: https://github.com/OAI/OpenAPI-Specification.

OpenAPI Specification lets you describe, produce, consume, and visualize RESTful APIs. RESTful APIs use HTTP requests to access and use data. Following the OpenAPI Specification in your builds generates documentation showing methods, parameters, and models. This also ensures that humans and computers alike understand your API calls.

To download Unqork’s OpenAPI Specification description format from our developer's page:

1.

Click on the following link: https://developers.unqork.io/.

2.

Click Download at the top of the page.

To learn more about how to use Unqork's OpenAPI Specification, search Testing API Endpoints Using Third-Party Applications in our In-Product Help.

API Specification Snippet

When building internal API modules, you'll use Unqork's API Specification snippet. Our team based this snippet on the OpenAPI Specifications description format. This snippet defines the standard format of all API modules made in Unqork. So, it would help to use the snippet when creating all your application's API modules. For example, let's say you have a module in your application that creates submissions. The best practice is to set your module up using the API Specification snippet. Then you can configure or change settings as you wish. The snippet is a great guide to ensure your API calls work correctly.

To learn more about the API Specification snippet, search API Specification Snippet in our In-Product Help.

We made it easy to create an API module using the API Specification snippet. These instructions assume you have the snippet downloaded from Marketplace, a module open, saved, and with a title.

1.

In the left sidebar of Module Builder, click the Snippets button.

2.

Enter API Specification in the search bar.

3.

Drag and drop the API Specification snippet onto your canvas.

4.

Save your module.

It's as easy as that! This snippet will correctly define, in a standardized format:

• What your API call does.

• The request parameters of the call.

• The expected response of the API call.

Following API Specifications ensures everyone understands your API call, no matter how you configure it.