Handling Blobs in the REST Interface
The Designer can handle blob parameters in the body of a REST interface for requests and responses. Blobs may contain different content types. How the content types should be handled can be configured on client and server side by four attributes provided by stereotype REST Operation for REST APIs and REST adapters.
For REST adapters, you can change the options listed below on manually created REST interfaces, or once you have copied your connector definitions to the API folder of your service.
Find below an overview on these attributes and what combinations make sense.
Direction | Attribute | Description | Adapter Implementation | API Implementation |
|---|---|---|---|---|
Request | Accepted Request Content Type | Defines the content types of the request body. | Specify which content type you are sending with your request. | Define which content types the endpoint accepts. |
Reject Other Request Content Types | Triggers a content type check by the xUML Runtime. | Specifies if the REST adapter should reject calls to this endpoint if a request uses a custom content type that does not match the content types listed in Accepted Request Content Type. This can be the case if you set the "Content-Type" header manually. If set to true, and the "Content-Type" header does not match, the adapter does not contact the endpoint at all but rejects calls with an exception ( | Define if other content types than defined with Accepted Request Content Type should be rejected with HTTP 415 (Unsupported Media Type). The Runtime reads the related "Content-Type" header and compares it to the content types that are accepted by the service (Accepted Request Content Type). | |
Response | Blob Body Content Type | Defines the content type of the response body. | Specify a list of content types you accept as a response. | Define which content types the endpoint can return to the client. |
Reject Other Response Content Type | Triggers a content type check by the xUML Runtime. | Specifies if the REST adapter should reject calls to this endpoint if a request uses a custom content type that does not match the content types listed in Blob Body Content Type. This can be the case if you set the "Accept" header manually. If set to true, and the "Accept" header does not match the content types the service can provide, the adapter does not contact the endpoint at all but rejects calls with an exception (S | Define if the service should reject the request with HTTP 406 (Unsupported Media Type) if the client request has accept headers that differ from the ones defined with Blob Body Content Type. The Runtime reads the related "Accept" header and compares it to the content types that can be provided by the service (Blob Body Content Type). |
Examples
The RESTAPI_BlobContent_Example and the RESTAdapter_BlobContent_Example implement a server and a client that exchange blob content (pictures). They have the following blob content setup implemented:
Server (RESTAPI_BlobContent_Example) | Content Type Settings | Description | ||
|---|---|---|---|---|
Store a picture | POST /picture | Accepted Request Content Type | image/png;image/jpeg | The server can store PNGs and JPGs. |
Return a picture by id | GET /picture/<an id> | Blob Body Content Type | image/png | The server returns PNGs upon request. |
Client (RESTAdapter_BlobContent_Example) | Content Type Settings | |||
Send a picture | POST /picture | Accepted Request Content Type | image/png | The client sends PNGs. |
Retrieve a picture | GET /picture/<an id> | Blob Body Content Type | image/png;image/jpeg | The client accepts PNGs and JPGs as a response. |
Good Cases
The following table shows some example calls and how they would be executed.
Client | Generated Header | Server | |||
|---|---|---|---|---|---|
1 | Store a picture | POST /picture | Content-Type: image/png | → | accepts request |
← | returns id | ||||
2 | Retrieve a picture | GET /picture/123456 | Accept: image/png | → | accepts request |
Content-Type: image/png | ← | returns picture PNG | |||
Error Cases
The following table shows some error cases and their consequences if you do not rely on the automatically generated headers but set your own headers instead.
Example | Client | Custom Header | Server | ||
|---|---|---|---|---|---|
1 | Store a picture, wrong content type | POST /picture | Content-Type: image/svg+xml | → | accepts request |
| |||||
2 | Store a picture, wrong content type, | POST /picture | Content-Type: image/svg+xml | → | Reject Other Request Content Types = true |
← |
| ||||
3 | Store a picture, wrong content type, | POST /picture | Content-Type: image/svg+xml | ↓ | not called at all |
| ← | ||||
4 | Retrieve a picture, wrong content type | GET /picture/123456 | Accept: image/svg+xml | → | accepts request |
| |||||
5 | Retrieve a picture, wrong content type, | GET /picture/123456 | Accept: image/svg+xml | → | Reject Other Response Content Type = true |
← |
| ||||
RESTAdapter_SupportManager_Example
Click there to download a simple example model that shows the usage of the REST adapter in Scheer PAS Designer.
RESTAdapter_BlobContent_Example
Click here to download a simple example model that shows how to handle Blob content with a REST call in Scheer PAS Designer.