Handling Blobs in the REST API
The xUML Runtime can handle blob parameters in the body of a REST interface. This can be configured on a REST operation by four attributes that are provided by stereotype REST Operation.
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 |
← |
| ||||
RESTAPI_BlobContent_Example
Click here to download a simple example model that shows the implementation of a REST API that receives and returns Blob content with Scheer PAS Designer.