Support for multipart/form-data content type
Though application/x-www-form-urlencoded is a more natural way of encoding, it becomes inefficient for encoding binary data or text containing non-ASCII characters. The media type multipart/form-data is the preferred media type for request payloads that contain files, non-ASCII, and binary data. CloudStreams supports this media type using which you can embed binary data such as files into the request body in a transparent way.
A multipart/form-data request body contains a series of parts separated by a boundary delimiter, constructed using Carriage Return Line Feed (CRLF), "--", and also the value of the boundary parameters. The boundary delimiter must not appear inside any of the encapsulated parts.
Each part must contain a Content-Disposition header field where the disposition is form-data. The Content-Disposition header field must also contain an additional parameter of name. For form data that represents the content of a file, a name for the file should be supplied as well, by using a filename parameter of the Content-Disposition header field.
Each part may have an optional Content-Type header field which defaults to text/plain. If the contents of a file are to be sent, the file data should be labeled with an appropriate media type, if known, or application/octet-stream.
Example of a multipart request
--BOUNDARY
Content-Type: application/json
Content-Disposition: form-data; name="job"
{
"object":"Contact",
"contentType":"CSV",
"operation":"insert"
}
--BOUNDARY
Content-Type: text/csv
Content-Disposition: form-data; name="content"; filename="content"
(Content of your CSV file)
--BOUNDARY—
Parts for a REST resource
CloudStreams defines the following three part types:
Part Type | Description |
TEXT | Represents a simple text part of a multipart/form-data payload where the content of the part is of type text/plain. You can use this part to send raw text data as the content of a part, in a multipart request. From a file upload perspective, this part is generally used to convey extra information about the upload behavior, like target folder paths/folder names where the file has to be uploaded. |
FILE | Represents a binary part of a multipart/form-data payload where the content of the part is binary or the content of the file itself. To upload a file, you will normally use this part. For file upload kind of use cases, this part is the main or mandatory part required by the service provider. Note: There is no limit in terms of the size of the file part that you can send as part of multipart. It depends on the available heap space. |
DOCUMENT | Represents a part where the content of the part is of type application/json or application/xml. |
Defining the parts for a REST resource
You can define the parts for a REST resource in the following ways:
Connector XML
Service Development perspective in
Software AG Designer Using the Connector XML to define the parts for a REST resource
If you are a connector developer and are sure about all combinations of all the parts for a REST resource, add the part definitions under Resource Definitions in the Connector XML file. This reduces your effort while developing cloud connector services as you can just create and run the cloud connector services and there is no need to add any parts by using the Service Development perspective in Software AG Designer. In the Connector XML file, if the isRequired attribute of the part element is set to true, the part will be available in the service signature. If isRequired is marked as false, the part appears in the Attachment table but does not appear in the signature. You can still add a new part by using the Service Development perspective in Software AG Designer.
TEXT - In this definition, the following table describes the various attributes of the part element:
Attribute Name | Description |
name | Name of the part. |
contentType | Content type of the part's content. |
Type | Part type, for example, here it is TEXT. |
defaultValue | If provided, sets as the value of this text part. |
isRequired | Represents whether this part will be included in the signature. |
The following example shows how the file uploading path, sampleFolder, is sent using a text part.
Note: Set the messageFormatterType attribute of the request element as multipart/form-data. This will denote this resource as a multipart form-data resource.
FILE - In this definition, the following table describes the various attributes of the part element:
Attribute Name | Description |
name | Name of the file part. |
contentType | Content type of the file that is being uploaded. |
Type | Part type, for example, here it is FILE. |
defaultValue | If provided, sets as the filename by which it will be uploaded. |
isRequired | Represents whether this part will be included in the signature. |
The following example shows how a raw file takeit.txt having content type text/plain is sent using a file part.
DOCUMENT - In this definition, the following table describes the various attributes of the part element:
Attribute Name | Description |
name | Name of the file part. |
contentType | The serialization type to which the document will be serialized and become the part content. CloudStreams supports only application/json and application/xml as the content type for this part. |
Type | Part type, for example, here it is DOCUMENT. |
defaultValue | If provided, sets as the document reference. |
isRequired | Represents whether this part will be included in the signature. |
Example: You want to send the following JSON payload, which is of type application/json as the part's content.
{
"object":"Contact",
"contentType":"CSV",
"operation":"insert"
}
To transmit this payload in a part, you have to create an Integration Server document, for example, metadata, which will contain three string fields.
In this example, the fields are object, contentType, and operation. You have to point the document namespace as the default value, in this example, multipart.sample:metadata, and the content type as application/json. CloudStreams can now serialize the Document and make it available as the content of the document part.
The following is a sample part definition for the Document part:
Using the Software AG Designer to define the parts for a REST resource
This approach allows the service developer to add parts, after creating the cloud connector service. The Attachment panel in the Service Development perspective in Software AG Designer lists all the parts that have been added.
TEXT - In the
Name field, type the name of the file part as documented in the SaaS provider API documentation. The
Name field is mandatory. In the
Value field, type the value of the part. If you do not give any value, an empty string will be set as the default value.
FILE - In the
Name field, type the name of the file part as documented in the SaaS provider API documentation. The
Name field is mandatory. In the
Content Type field, type the content type of the file you are uploading. If you do not give any value, the default value will be set as application/octet-stream. In the
File Name field, type the file name by which you want the file to be uploaded. If you do not give any value, the default value will be set as
attachment.
DOCUMENT - In the
Name field, type the name of the file part as documented in the SaaS provider API documentation. In the
Content Type field, type the content type of the body part that you want your document to be serialized and sent to the back end.
CloudStreams supports only
application/json and
application/xml as the content type for this part. For the
Document field, first create a document that matches the payload and then select that document. The
Name,
Content Type, and
Document fields are mandatory.
Note: All options including the Add Part option are disabled if the resource is not of type multipart/form-data. Currently, multipart/form-data payload is supported only at the request level, that is, only in the input signature.
If you do not provide the optional values, CloudStreams sends the default values as mentioned in the following table to the back end.
Part Type | Field Name | Default Value |
TEXT | Value | Empty string |
FILE | Content Type | application/octet-stream |
FILE | File Name | attachment |
See the Building Cloud Connector Services section in the webMethods Service Development Help for more information on how to add parts using Software AG Designer.
