Managing Multipart/Form-Data Uploads

In some cases, operations uploading data to the platform use the Multipart-Form Data content type. This more complex media type allows upload of more than one type of data, separated by boundaries with a unique ID.

This document includes some examples to show you how the headers might look on these operations, and/or how you might run the operation in a web client that supports file upload, such as Postman (https://www.getpostman.com/).

It includes:

Operations that use the multipart/form-data Content-Type header for file upload

Some operations that use file upload are shown in the table below.

Service Endpoint Description
Apps POST /api/apps/versions/{AppVersionID}/keyinfo

Adds an app's public key or certificate (for runtime security).

For an example, see Apps Service: Save Key Info below.

Boards POST /api/boards/items/{BoardItemID}/artifacts Adds an artifact, such as an uploaded image or file, to be used in the markdown for a Board item that is being edited (subsequent artifact, after the first).
Boards POST /api/boards/items/comments/{CommentID}/artifacts Adds an artifact, such as an uploaded image or file, to be used in the markdown for a comment that is being edited (subsequent artifact, after the first).
Boards POST /api/boards/items/artifacts Adds the first artifact, such as an uploaded image or file, to be used in the markdown for a Board item that is being created.
Boards POST /api/boards/items/comments/artifacts Adds an artifact, such as an uploaded image or file, to be used in the markdown for a comment that is being created (first artifact).
Console Resources POST /resources/{path:.*} Uploads a developer portal resource, such as a stylesheet, to the /resources/ folder structure.
Content POST /content/{path} (with specific content-type) Uploads a single file of existing content to the platform, or uploads a ZIP file of existing content and unzips it to the specified location.
Dropbox POST /api/dropbox/pictures

Uploads an image, for a resource such as a user profile, to the Dropbox.

For an example, see Dropbox Service: Add Picture below.

Tenant Administration POST /api/tenants/{FedmemberID}/packages

Imports information that was previously exported from a platform version.

For an example, see Tenant Administration Service: Import Package below.

Workflow POST /api/workflow/definitions Adds a new workflow for the developer portal.

Apps Service: Save Key Info

One example of an operation that uses this media type in the Content-Type request header, in the application service, uploads the app's certificate signing request (CSR) or security certificate: POST /api/apps/versions/{AppVersionID}/keyinfo.

An example of the multipart-form data header for this operation is shown below. Line breaks have been added to the Cookie header and the CSRF token for display purposes.

POST http://{hostname}/api/apps/versions/9vQtwz5cVjB4Lb0tW7YDoRGm.acmepaymentscorp/keyinfo?wrapInHTML=true HTTP/1.1
Host: {hostname}
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Cookie: AtmoAuthToken_acmepaymentscorp=TokenID%3Db2f87d98-a01e-11e4-a4c8-c152b79a9472%2Cclaimed_id
%3Durn%3Aacmepaymentscorp%3Auser%3Aacmepaymentscorp%3A7222fcd1-fe4b-4b80-ad25-ec86981c7962%2C
issueTime%3D1421701444022%2CexpirationTime%3D1421703244005%2CAttributesIncluded%3Dfalse%2C
UserFDN%3D7222fcd1-fe4b-4b80-ad25-ec86981c7962%252Eacmepaymentscorp%2CUserName%3D
adminacmepaymentscorp%2Csig%3DNE567Vbh1ZdIE1Yx6HlnQF9zFwy2-xKqq-EquYiugI-k2_jzUR9rvV0x
kyLDg8_CBL68dAqCfq1VXSghLjvFV2nreg4WLlR-mhBrOa209ZT7pgryPCTg-wlEL3e_zq-9lsoGxPPRSyCvRXqwz
urhLLM_9GWokQoZUYsXrTP6Jx8; Csrf-Token_acmepaymentscorp=TokenID%3Db2f87d98-a01e-11e4-a4c8-c
152b79a9472%2CexpirationTime%3D1421703244028%2CUserFDN%3D7222fcd1-fe4b-4b80-ad25-ec86981c79
62%252Eacmepaymentscorp%2Csig%3DIid5J_crulvfYk5hHYGUt6fCbZvpp4nACDBA7JIqIMGbDZXaaItzW87rrPx
PBazCQ-N8BacJcrEsib8bWmeGNZPqWgtXiFtRZcHBakb5zyFwLuSCE9RQK5lu8mg2iFfRH9Cm_ER
MqGUW2q28agiMT36tJWZ6SN9F8-JG6tRnYjA
Content-Type: multipart/form-data; boundary=---------------------------138372179114855

-----------------------------138372179114855
Content-Disposition: form-data; name="Certificate"; filename="cert.csr"
Content-Type: application/txt

-----BEGIN CERTIFICATE REQUEST-----
MIIClzCCAX8CAQAwVDEPMA0GA1UEAxMGUmFtZXNoMQwwCgYDVQQLEwNQRE8xDDAKBgNVBAoTA1NP
QTELMAkGA1UEBxMCTEExCzAJBgNVBAgTAkNBMQswCQYDVQQGEwJVUzCCASIwDQYJKoZIhvcNAQEB
BQADggEPADCCAQoCggEBAIheb0Q2+PkfDwnxtdR+FLgMcNNRGuAy5pp8ku4VPpEt95//jJ+BRc52
zHc++FfSlDHOvn/N++1ZA+KM7PdpnJPYCu8ZDIkT2WVB+0CmuIRw9uToBdctLjpvBe1NLC/io7FD
UADSzXRu2/Iqv8Idj9UQSObrBiYPY5KIFtPA7M4b54M35YV6BHWg+eZ+vLEeSGpbsuA8TlbFKJF4
rrQApTPtcJkju7EMeBdkvRr7uKHSfSYCHQXPT8cYr6pVzq+dh38f960deS0QyHag3/d09fy7Ahmj
Re8ieWufYW6b9LsJut9hW9EmfM38sTcq2jFWvHUstl2qq4QcxG/X9SVJnPUCAwEAATANBgkqhkiG
9w0BAQUFAAOCAQEAcxkJWbv06sKseT5XSBrDCP2KiCdTv2BIgsZzGs0A56DmDj6Jbw3zfS/sgrO3
uN2nIp5zfiy9TzyAIN8Gs7DRKVBPptPARRXaSk6RhbrrjLg+erpFuNzHUmc9HAeXu6/MbnFDpLcr
lhRgJ495OhI+hEVGjCqcObSD2NqSTs4q8FtkVOegpEIHLJSgoZfBKAq8eo4DUTvr9oSpcHxg1ExA
xYAm6hfXZX9ucHM8X8U69H1LZm491mcp1svinseSlkh/q2Y1aHCyMYjWajHvbZbF5pw8zgFCespp
7a9BMDlEtvG2btQgd6sRv3rSWVEzXeMoJPFx/QKJGDyRc1luekrroA==
-----END CERTIFICATE REQUEST-----

-----------------------------138372179114855
Content-Disposition: form-data; name="Comments"

testing
-----------------------------138372179114855
Content-Disposition: form-data; name="X-Csrf-Token_acmepaymentscorp"

TokenID%3Db2f87d98-a01e-11e4-a4c8-c152b79a9472%2CexpirationTime%3D1421703244
028%2CUserFDN%3D7222fcd1-fe4b-4b80-ad25-ec86981c7962%252Eacmepaymentscorp
%2Csig%3DIid5J_crulvfYk5hHYGUt6fCbZvpp4nACDBA7JIqIMGbDZXaaItzW87rrPxPBaz
CQ-N8BacJcrEsib8bWmeGNZPqWgtXiFtRZcHBakb5zyFwLuSCE9RQK5lu8mg2iFfRH9
Cm_ERMqGUW2q28agiMT36tJWZ6SN9F8-JG6tRnYjA
-----------------------------138372179114855--

Back to top

Dropbox Service: Add Picture

The example below illustrates how you might use Postman to upload the avatar for a user.

Note: In this example, the CSRF header setting is not enabled for POST operations in the platform settings, so the X-Csrf-Token_{fedmemberID} header is not required. If you need to include this header for your own implementation, see CSRF Prevention on the Platform.

Prerequisites
  • The user whose picture is being added must log in. See POST /api/login. Uploading an avatar can only be done by an authorized user. For example, for an API, it must be an API Admin or Business Admin; for a platform user, it must be the user or a Site Admin.

    In fact, you'll be able to upload the avatar, but you won't be able to assign it to the user profile, which is a later step; see Next Steps below.

  • You'll need an avatar image ready to upload.
Settings in Postman

The example below uses the POST /api/dropbox/pictures operation.

Headers

No settings are required in the Headers section; the values are set in the Body section.

Add Picture in Postman: Headers

Body

The key name is Profile and the value is the avatar filename, as shown below. You must navigate to the file in Postman via the Choose Files button.

Add Picture in Postman: Body

Result

The image is uploaded to the Dropbox, and the Dropbox ID is returned, as shown below.

Add Picture in Postman: Result

Next Steps

To finish setting up the avatar, two more operations are required:

  1. Assigns the crop dimensions to the image: PUT /api/dropbox/pictures/{pictureId}
  2. Modifies the user's profile with the new image: PUT /api/users/{UserID}

Back to top

Tenant Administration Service: Import Package

The example below illustrates how you might use Postman to import business information, previously exported from a platform version using the Actions menu in the context of a business organization: in the API, the GET /api/businesses/{BusinessID}/package operation. To import the information you'll use the POST /api/tenants/{FedmemberID}/packages operation.

Note: In this example, the CSRF header setting is not enabled for POST operations in the platform settings, so the X-Csrf-Token_{fedmemberID} header is not required. If you need to include this header for your own implementation, see CSRF Prevention on the Platform.

Prerequisites
  • The user running the operation must be logged in, and must have appropriate permissions; must be a Site Admin.
  • You'll need the business-export.zip file, previously exported from a platform version. The example below doesn't use a migration properties file, but if you're using migration properties you'll need to have that file also, as covered in the documentation for this operation.
Settings in Postman

The example below uses the POST /api/tenants/{FedmemberID}/packages operation.

Headers

The Accept header is application/json, as shown below. The Content-Type header is not specified; instead, the values are set in the Body section.

Import Package in Postman: Headers

Body

The key name is Package and the value is the business-export.zip file, as shown below. You must navigate to the file in Postman via the Choose Files button.

Import Package in Postman: Body

Result

The business information is uploaded to the platform, and an HTTP Status 200 is returned with a null value, as shown below.

Import Package in Postman: Result

Back to top

Related Topics