REST Adapter Reference

This page explains the REST Adapter in Bridge context. If you were looking for the same information regarding the PAS Designer, refer to REST Adapter in the Designer guide.

Tagged Values

<<RESTAlias>>

<<RESTAdapter>>

<<RESTInterface>>

This stereotype defines a package as REST interface. It has no additional tagged values.

<<RESTResource>>

<<REST>>

Since Runtime 2022.6 the Runtime uses Transfer-encoding: chunked for POST requests.

Tagged Value	Description	Allowed Values
Http Method (httpMethod)	Provide the HTTP method of this REST method should respond to.	a valid HTTP method	GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
		none	method name, if it is one of: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS (with optional trailing '/') GET otherwise
Relative Path (relativePath)	Defines the path of the REST method in relation to the parent resource.	none	The name of the REST method will be used.
		any valid string	The given name will be used. The relative path may also contain variables (REST path parameters, specified as :<variable name>) and can be segmented like e.g. /date=:<a date variable>.
Is Verbatim Path (isVerbatimPath)	Disable most of the path normalization. All escaping must be done manually, leading or trailing whitespaces are preserved. This is what still will be done, if isVerbatimPath is set to true: variable discovery The E2E Runtime will try to find and replace variables (:<my variable name>). colon escaping If the path contains a colon that (and that does not indicate a path parameter), you can escape this colon by another one, like :: (e.g. /myAPI/resource/aText::anotherText/:variable). correction of segment delimiters The E2E Compiler adds a leading slash (if not present), removes trailing slashes (if present) and removes duplicates slashes, e.g. myAPI//resource/:variable/ becomes /myAPI/resource/:variable.	true	Path should be treated as verbatim, path normalization is disabled.
		false (default)	Path should be URL encoded.
Blob Body Content Type (blobBodyContentType)	Specify the content type (as defined in RFC 7231) that the request will be sending. The Runtime generates a matching "Content-Type" header to your request. Refer to Handling Blobs in the REST Interface for a deeper explanation and some examples. This tag must be left unset if no Blob output parameters are used. In future versions, the effect of this tag may be extended to other contexts as well.	a list of valid media ranges	e.g. application/msexcel Default is application/octet-stream if not specified.
Reject Other Response Content Type (rejectOtherResponseContentTypes)	Runtime 2021.6 Builder 7.15.0  The xUML Runtime performs a verification of the content-type header for REST responses. Specify whether to return an error (HTTP 406, not acceptable) on responses with a content type that does not conform with the content types specified in Blob Body Content Type . Refer to Handling Blobs in the REST Interface for a deeper explanation and some examples.	true	Reject to perform adapter call if the header "content-type" does not match the values listed in Blob Body Content Type (default) . Exception: RESTLM/48: Request content type not declared as accepted by the service
		false	Perform the adapter call in spite of content-type header mismatch, and let the service handle this.
Accepted Request Content Type (acceptedRequestContentType)	Runtime 2021.6 Builder 7.15.0  Provide a list of content types you accept as a response. This must be a list of valid "accept" headers as defined in RFC 7231. The Runtime generates a matching "Accept" header to your request. Refer to Handling Blobs in the REST Interface for a deeper explanation and some examples. This tag must be left unset if no Blob output parameters are used. In future versions, the effect of this tag may be extended to other contexts as well.	a list of valid media ranges	e.g. application/xhtml+xml Default is application/octet-stream if not specified.
Reject Other Request Content Types (rejectOtherRequestContentTypes)	Runtime 2021.6 Builder 7.15.0  Specify whether to return an error on requests with a content type that does not conform with the content types specified in Accepted Request Content Type . Refer to Handling Blobs in the REST Interface for a deeper explanation and some examples.	true	Reject to perform adapter call if the header "accept" does not match the values listed in Accepted Request Content Type (default). Exception: Set "accept" header does not accept any of declared response content types
		false	Perform the adapter call in spite of accept header mismatch and let the service handle this.

<<RESTParameter>>

<<RESTError>>

Stereotype <<RESTError>> is used on a class to mark it as REST error class. Assign such a class to the REST port type (see REST Service Reference#<<E2ERESTPortType>>) and this class will be used as output in case of error. Each REST port type can have its separate error class.
You can report errors back to the caller using something like:

local response = getRestHttpResponse();
response.responseObject = <my error object>;
response.httpStatus = <a matching http error code>;

<<RESTResponseDefinition>>

Use dependencies with stereotype <<RESTResponseDefinition>> are used to connect REST resources with REST error classes.

REST Adapter Parameters

REST Utility Functions

Access to HTTP request and response objects is provided through global methods: getRestHttpRequest()and getRestHttpResponse().

local request = getRestHttpRequest();

local response = getRestHttpResponse();

REST Content Types

With the REST Adapter, the E2E Runtime can handle JSON or XML as content types. The E2E Runtime will parse either response content (JSON or XML) to a response object automatically.
You do not need to set any headers. If no headers are set, the Runtime will use JSON as a default format and set Accept header to application/json,text/json,application/xml;q=0.9,text/xml;q=0.9,*/*;q=0.8.

If you want to control the REST request and response formats, you can set the Content-Type and Accept headers as described on Setting REST Request Options.

• Set the Accept header to the content type, you want the REST service to send back as a response.
  • application/json for JSON
  • application/xml for XML
  The E2E Runtime will deduce the Content-Type header accordingly.

This mechanism also works vice versa: setting the Content-Type header and letting the E2E Runtime deduce the Accept header:

• Set the Content-Type header to the content type, you want to send to the REST service.
  • application/json for JSON
  • application/xml for XML
  The E2E Runtime will deduce the Accept header accordingly to
  • application/json,text/json,application/xml;q=0.9,text/xml;q=0.9,*/*;q=0.8 for JSON
  • application/xml,text/xml,application/json;q=0.9,text/json;q=0.9,*/*;q=0.8 for XML
  This approach gives the REST service a wider range of content types for sending the response.

Setting the content type headers to any value other than JSON or XML is not supported and the E2E Runtime will throw an exception in this case.

Regarding response parsing, the E2E Runtime will process REST responses as follows:

• If the Content-Type header of the response is JSON or XML, respective format will be used (regardless what is specified in the Accept header).
• If the Content-Type header of the response is not set, the E2E Runtime will assume that the content matches the Accept header of the request. If no Accept header has been specified, JSON is the fallback.
• In case of unsupported Content-Type, JSON is the fallback.
  If the log level of the service is set to Debug, the E2E Bridge will log details about unsupported Content-Types to the bridgeserver log. Refer to xUML Service Standard Log for more information on the bridgeserver log.

REST Parameter Types

Request

Response

RequestOptions

AdapterResponse

Request and Response Types