APIs: Connecting Your Apps
Overview
Application programming interfaces, or APIs 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., are a standardized way of requesting or sending data between systems. It’s difficult to generalize all types of API calls, but APIs typically allow the first system to request information from the second system. Then, the second system returns the information to the first system.
For example, if you open up the Uber app on your phone, you’ll see a map that looks like Google Maps. That’s because the Uber app uses a Google Maps API to bring data from Google Maps into the Uber app. When you determine a destination on the app, you request that location data from the Google Maps API. The API then returns the location data to the app to display on your phone.
What Is an API?
Unqork uses REST (Representational State Transfer) APIs. REST, or RESTful APIs, are a set of guidelines that define how two systems interact with each other. We refer to these two systems as the Client and Server. REST APIs are easy to use and understand and allow flexibility and scalability. REST APIs are also common, making it easy to use them internally and externally in Unqork.
Making an API call requires a few crucial attributes:
-
Data Source URL
-
HTTP Request Method
-
Header
-
Request Body
-
Parameters
Data Source URL
The Data Source URL is necessary for the API to retrieve data. In Unqork, the Data Source URL also acts as a form of authentication. Without access to an Unqork environment, you cannot use its URL to perform API calls.
The fundamental URL structure to retrieve or manipulate data is https://{subdomain}.unqork.io/api/1.0/, where the {subdomain} represents your Unqork environment. For example, training.unqork.io/api/1.0/.
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) request method. The request method determines the API’s intended action. For example, if you use an API to retrieve data, your API makes a GET call. Request methods include:
-
GET: Retrieves data.
-
POST: Creates data.
-
PUT: Updates existing data.
-
PATCH: Replaces existing data.
-
DELETE: Deletes data.
Header
All API requests and responses include a header that contains metadata or other data information exchanged between the API and the client. In Unqork, the most common information in the header is the content–type, and authorization.
The content-type specifies the type of data being transmitted, so it can interpret and process it. Because Unqork’s platform relies on JSON, and the most common content-type is application/json.
The header also contains the necessary authentication to interpret and process the data. There are many ways to authenticate APIs in Unqork, but the simplest way is using a Bearer token. Bearer tokens take the form of cryptic strings generated by the integrated service. When you submit a request using a Bearer token, you do not need to request on behalf of the client. Instead, you request on behalf of an application. Common API services that need Bearer tokens are SendGrid, Postman, and Twitter.
When using a Bearer token for authentication, it displays in the header as Authorization: Bearer <access-token>, where <access-token> is the unique API key you must obtain for the service whose API you want to use.
For more information on using Bearer tokens in Unqork, see our API Authentication Bearer Token article.
Request Body
Many times, you need to send payload information to the server for it to understand your request. The APIs request body includes any data sent between the client and the server. For example, a user ID, email address, or phone number. The only HTTP method type that does not require a body is a GET API call.
If you use Unqork’s Create Module Submission(s) API, it isn’t enough to tell the server this is a POST method type. You must also include the actual data to store in the submission. To do this, you’ll use the same JSON format as the request body:
{
"userId": "string",
"data": {},
"metadata": {}
}
The parameters required for each API vary. You can find more information about each API call by visiting Unqork’s developers.unqork.io.
Response
Every successful API request results in an API response. What is included in the response depends on the HTTP request method you are using. Therefore, the response can contain data you created, deleted, retrieved, or updated. The response also contains all the critical attributes discussed above, like the header, HTTP request method, and the Data Source URL.
Continuing with the example before, after sending an API request using Unqork’s Create Module Submission(s) API, you’ll see the following example response:
POST https://{subdomain}.unqork.io/api/1.0/modules/{moduleId}/submissions
Content-Type: application/json
{
"id": "string",
"userId": "string",
"moduleId": "string",
"created": "2019-08-24T14:15:22Z",
"modified": "2019-08-24T14:15:22Z",
"deleted": "2019-08-24T14:15:22Z",
"data": {
"rawData": {}
},
"metadata": {},
"validationErrors": [
{
"id": "string",
"path": "string",
"label": "string",
"parent": "string",
"message": "string"
}
]
}
Path Parameters
To make a successful call, your API must contain the appropriate HTTP method. Depending on your method, you might need to include other parameters, like path or query parameters.
For example, if you use the Get Module Submissions API in Unqork, you’ll use the GET HTTP method. You also need to provide the server URL where you’ll retrieve your module submissions.
That URL looks like the following:
https://{subdomain}.unqork.io/api/1.0/modules/{moduleId}/submissions
The {subdomain} represents your environment while the {moduleID} represents the module storing the data you're trying to retrieve. The {subdomain} and {moduleId} are called path parameters.
If you use Unqork’s internal API services, the URL is automatically provided with placeholder text for you to replace—much like the example above.
Unqork's Internal API
The Unqork Platform is built on top of an API. This API lets you access certain types of data from the entire Unqork Platform.
A few examples include:
-
Sending sensitive submission data directly to clients instead of storing that data on our server.
-
Populating and exchanging data between modules in Unqork.
-
Creating users, updating submissions, and executing or promoting modules.
You'll find a list of all Unqork API calls at developers.unqork.io. Or, you can click the Learn More button in the Plug-In component's configuration window.
External APIs
Retrieving data from external applications (like DocuSign and Salesforce) requires integration with an external API service. With external APIs, you can take advantage of features otherwise not available with the Unqork internal API. For example, connecting your client's CRM (customer relationship management) system to a Salesforce instance or a DocuSign account.
To learn more about configuring external API calls, see our External APIs article.
Resources
