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
- Apps Service: Save Key Info
- Dropbox Service: Add Picture
- Tenant Administration Service: Import Package
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 Community Manager 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 | Uploads a new workflow definition file to the Community Manager 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.
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%3Db1f87d98-a01e-11e4-a4c8-c152b79a9472%2Cclaimed_id%3Durn%3Aacmepaymentscorp%3Auser%3Aacmepaymentscorp%3A7222fcd1-fe4b-4b80-ad25-ec86981c7962%2CissueTime%3D1421701444022%2CexpirationTime%3D1421703244005%2CAttributesIncluded%3Dfalse%2CUserFDN%3D7222fcd1-fe4b-4b80-ad25-ec86981c7962%252Eacmepaymentscorp%2CUserName%3Dadminacmepaymentscorp%2Csig%3DNE567Vbh1ZdIE1Yx6HlnQF9zFwy2-xKqq-EquYiugI-k2_jzUR9rvV0xkyLDg8_CBL68dAqCfq1VXSghLjvFV2nreg4WLlR-mhBrOa209ZT7pgryPCTg-wlEL3e_zq-9lsoGxPPRSyCvRXqwzurhLLM_9GWokQoZUYsXrTP6Jx8; Csrf-Token_acmepaymentscorp=TokenID%3Db1f87d98-a01e-11e4-a4c8-c152b79a9472%2CexpirationTime%3D1421703244028%2CUserFDN%3D7222fcd1-fe4b-4b80-ad25-ec86981c7962%252Eacmepaymentscorp%2Csig%3DIid5J_crulvfYk5hHYGUt6fCbZvpp4nACDBA7JIqIMGbDZXaaItzW87rrPxPBazCQ-N8BacJcrEsib8bWmeGNZPqWgtXiFtRZcHBakb5zyFwLuSCE9RQK5lu8mg2iFfRH9Cm_ERMqGUW2q28agiMT36tJWZ6SN9F8-JG6tRnYjA
X-Csrf-Token_acmepaymentscorp: TokenID%3D8ed70a13-8469-11e8-b37a-b155e4eabeb8%2CexpirationTime%3D153...
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%3Db1f87d98-a01e-11e4-a4c8-c152b79a9472%2CexpirationTime%3D1421703244028%2CUserFDN%3D7222fcd1-fe4b-4b80-ad25-ec86981c7962%252Eacmepaymentscorp%2Csig%3DIid5J_crulvfYk5hHYGUt6fCbZvpp4nACDBA7JIqIMGbDZXaaItzW87rrPxPBazCQ-N8BacJcrEsib8bWmeGNZPqWgtXiFtRZcHBakb5zyFwLuSCE9RQK5lu8mg2iFfRH9Cm_ERMqGUW2q28agiMT36tJWZ6SN9F8-JG6tRnYjA
-----------------------------138372179114855--
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.
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.
Result
The image is uploaded to the Dropbox, and the Dropbox ID is returned, as shown below.
Next Steps
To finish setting up the avatar, two more operations are required:
- Assigns the crop dimensions to the image: PUT /api/dropbox/pictures/{PictureID}
- Modifies the user's profile with the new image: PUT /api/users/{UserID}
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.
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.
Result
The business information is uploaded to the platform, and an HTTP Status 200 is returned with a null value, as shown below.
