Introduction to Multipart APIs
Overview
From time to time, your API (application programming interface) request will include more than just an end-user’s module submission. Maybe you need your end-user to upload supporting documents or proof of identity. Some APIs need you to combine these files with the rest of the data in your API request. To combine these files, you’ll use a multipart API call.
NOTE Multipart APIs generally work with POST or PUT HTTP methods. This is not always the case though. Before setting up a multipart API, check the specific API documentation to see if a multipart call is an option.
What You'll Learn
In this
-
What a multipart API call is.
-
How to set up a multipart API call in Unqork.
What is a Multipart API Call?
A multipart API call combines two or more sets of data into a single request. For example, we can easily convert the data collected through an Unqork module into a JSON object. But some APIs may need PDFs and other media files to use a different format type. To send other file types through an API request, let's look at a few other API settings.
HTTP Content-Types
Inspect your page as you make an API call and look at your Request and Response Headers. You'll see an HTTP Content-Type that most likely reads application/json.
You can view your Request and Response headers using the Inspect console. To do this, follow these instructions:
| 1. | Right-click anywhere on the browser’s page. |
| 2. | Click Inspect. The Inspect panel should pop up on the right side of the screen. |
| 3. | Click Network. The Headers panel automatically shows as below. |
This is the content-type for standard API calls like Create Module Submissions. But when you're making a multipart API call, you'll see something different. For multipart API calls, the content-type is multipart/form-data. While multipart/form-data is the most common, it's not the only type of multipart call. You may also encounter multipart/mixed and multipart/related. You can set these alternate content-types within the Plug-In component.
Still, changing the content-type of the request is only the first step. This only allows you to send multiple parts within one request body. You’ll also need to define each of those parts for your call to be a success. Those definitions are called MIME (Multipurpose Internet Mail Extension) Types.
Multipurpose Internet Mail Extensions (MIME) Types
Each part of your multipart API call can refer to a separate type of document or media. And you’ll need to define each document or piece of media for the system to understand what you’re sending. You’ll do this using something called MIME Types.
Here are some common file types that you'll come across, as well as their associated MIME Types:
|
Document Type |
MIME Type |
|---|---|
|
|
application/pdf |
|
JPEG |
image/jpeg |
|
Microsoft Excel |
application/vnd.ms-excel |
|
MP3 Audio |
audio/mpeg |
NOTE These are only a few examples of common file types you might use within Unqork. You can find a more comprehensive list at https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types.
