Handling Blobs in the REST Interface

Runtime 2021.6 Builder 7.15.0 The xUML Runtime can handle blob parameters in the body of a REST interface. This can be configured by four tags on REST operations for REST service and REST adapter.

Find below an overview on these tags and what combinations make sense.

Location	Direction	Attribute	Description
Service	Request	Accepted Request Content Type	Define which content types the endpoint accepts.
	Request	Reject Other Request Content Types	Define if other content types should be rejected with HTTP 406 (Not Acceptable).
	Response	Blob Body Content Type	Define which content types the endpoint can return to the client.
	Response	Reject Other Response Content Type	Define if the service should reject the request with HTTP 415 (Unsupported Media Type) if the client request has divergent accept headers.
Adapter	Request	Accepted Request Content Type	Specify a list of content types you accept as a response. The Runtime generates a matching "Accept" header to your request.
	Request	Reject Other Request Content Types	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 accept header manually. If set to true, and the accept header does not match, the adapter does not contact the endpoint at all but rejects calls with an exception (S`et "accept" header does not accept any of declared response content types`).
	Response	Blob Body Content Type	Specify which content type you are sending with your request. The Runtime generates a matching "Content-Type" header to your request.
	Response	Reject Other Response Content Type	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 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 (`Request content type not declared as accepted by the service`).

Examples

Example File (Builder project Add-ons/REST):

<your example path>\Add-ons\REST\uml\restBlobContent.xml
<your example path>\Add-ons\REST\uml\accessRestBlobContent.xml

The example service provides a REST interface to store a blob to memory and retrieve stored blobs. The service accepts content type application/msexcel .

Server (restBlobContent.xml)		Content Type Settings		Description
Store a blob	POST /blob	Accepted Request Content Type	application/msexcel	The server can store Excel files.
Return a blob by id	GET /blob/<an id>	Blob Body Content Type	application/msexcel	The server returns Excel files upon request.
Client (accessRestBlobContent.xml)		Content Type Settings
Send a blob	POST /blob	Blob Body Content Type	application/msexcel	The client sends Excel files.
Retrieve a blob	GET /blob/<an id>	Accepted Request Content Type	application/msexcel	The client accepts Excel files 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 blob	POST /blob	Content-Type: application/msexcel	→	accepts request
1	Store a blob			←	returns id HTTP 201
2	Retrieve a blob	GET /blob/123456	Accept: application/msexcel	→	accepts request
2	Retrieve a blob		Content-Type: application/msexcel	←	returns Excel file

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.

Client			Custom Header	Server
1	Store a blob, wrong content type	POST /blob	Content-Type: application/msword	→	accepts request
1	Store a blob, wrong content type				handles wrong content type internally
2	Store a blob, wrong content type, server rejects other content types	POST /blob	Content-Type: application/msword	→	Reject Other Request Content Types = true
2				←	HTTP 406 (not acceptable)
3	Retrieve a blob, wrong content type	GET /blob/123456	Accept: application/msword	→	accepts request
3	Retrieve a blob, wrong content type				handles wrong content type internally
4	Retrieve a blob, wrong content type, server rejects other content types	GET /blob/123456	Accept: application/msword	→	Reject Other Response Content Type = true
4				←	HTTP 415 (Unsupported Media Type)

Related Pages: