Skip to main content
Skip table of contents

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.
The Runtime generates a matching "Content-Type" header to 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 (Endpoint '<endpoint URL>' does not declare '<content type>' as accepted content type).

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.
The Runtime generates a matching "Accept" header to your request.

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 (Set "accept" header does not accept any of declared response content types).

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
HTTP 201

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

  • handles wrong content type internally

  • RESTLM/11: Unknown input format (image/svg+xml)

2

Store a picture, wrong content type,
server rejects other content types

POST /picture

Content-Type: image/svg+xml

Reject Other Request Content Types = true

  • RESTLM/11 Unknown input format (image/svg+xml)

  • HTTP 415 (Unsupported Media Type)

3

Store a picture, wrong content type,
client rejects other content types

POST /picture
Reject Other Request Content Types = true

Content-Type: image/svg+xml

not called at all

  • RESTLM/7: Endpoint '<endpoint URL>' does not declare '<content type>' as accepted content type

4

Retrieve a picture, wrong content type

GET /picture/123456

Accept: image/svg+xml

accepts request

  • handles wrong content type internally

  • RESTLM/10: Cannot generate any of the expected output formats (image/svg+xml)

5

Retrieve a picture, wrong content type,
server rejects other content types

GET /picture/123456

Accept: image/svg+xml

Reject Other Response Content Type = true

  • RESTLM/10: Cannot generate any of the expected output formats (image/svg+xml

  • HTTP 406 (Not Acceptable)

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.