REST API Reference

port

Defines the machine port number the service is binding to.

any number
Using ports below 1024 may require additional privileges.

tracePort

Defines the shadow port of the service used for tracing.

any number (default is service port + 40000)

maxRequestBodySize

Specifies the maximum size of the request in KB (1 KB = 1024 Bytes). This can be used to prevent DoS or similar attacks. When the payload of the service exceeds the given maximum, incoming request are rejected.

any positive integer

0

Accept unlimited requests (default of services compiled with Builder versions < 7.12.0).

2048

2MB, default if not specified

maxRequestHeaderSize

Specifies the maximum size of the request header in KB (1 KB = 1024 Bytes). This can be used to prevent DoS or similar attacks. When the header payload of the service exceeds the given maximum, incoming request are rejected.

any positive integer

8

8 KB (default if not specified).

maxParallelConnections

Defines the maximum number of request that can be processed in parallel.

any positive integer

tokenType

Mark the service as to use token authorization. The REST Test Tool (API Management) will then present a field to enter the token and put the value into the HTTP headers. Refer also to tokenHeaderName for more information.

You can use both in a REST service: basic authorization and token authorization, see useBasicAuth.

none

Do not use token authorization.

API Key

Use API key authorization.

tokenHeaderName

Defines the name of the header that will transport the token. This tagged value is only relevant, if token authorization is enabled at all. The token header name will be presented as the name of the header field that can be entered in the Bridge REST Test Tool. Refer also to tokenType for more information.

A valid HTTP header name (according to RFC2616/RFC7230).

useBasicAuth

Mark the service as to use basic authentication mechanisms. The REST Test Tool (API Management) will then present fields to enter the credentials and put the values into the HTTP headers.

You can use both in a REST service: basic authorization and token authorization, see tokeType and tokenHeaderName.

true

Enable basic authentication.

false

Disable basic authentication (default).

jsonKeepNulls

When jsonKeepNulls is true, attributes of the REST response object having NULL values will be rendered to the REST response, otherwise they will be left out completely (see also chapter NULL Values).

true

Render attributes with NULL values to the REST response.

false

Leave out attributes with NULL values in the REST response (default).

jsonCompact

When jsonCompact is true, the JSON composer will generate compact JSON, otherwise it will generate pretty JSON.

true

Generate compact JSON (default).

false

Generate pretty JSON.

jsonWriteTypeDiscriminator

If jsonCompact is true, the JSON composer will generate xUML type properties ("e2e:type") to the generated JSON. If this option is true, the Runtime will write the original xUML type to the generated JSON in form of "e2e:type": "<name of the original xUML type>" if the type being serialized does not match the expected metadata. This is necessary if you want to convert the generated JSON back to an xUML class using jsonToClass().

true

Write xUML type discriminator.

false

Do not write xUML type discriminator.

path

Defines the path to this rest interface. If empty, the path is derived from the package structure.

none

path of the package structure will be used, e.g. /API/SupportCase/SupportAPI

any valid path string

path string starting with "/", e.g. /support

errorClass

Assigns a user-defined RESTError class to the REST interface. This class should be set in case of error and given back via the REST response.

any complex type describing the structure of the error

apiVersion

Defines the API version this port type provides (for documentation purposes only).

any string, default is 1.0.0

Relative Path
(relativePath)

Defines the path of the REST resource or collection in relation to the parent resource. You can provide a static path, or a dynamic path using the notation :<name of a REST Parameter>. You may also provide a combination of both.

none

the name of the REST resource will be used, e.g. /supportcases

any valid string

the given name will be used

a dynamic path supplying a REST parameter

dynamic path, the value of the REST parameter will be passed to the REST methods, e.g. :id

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 xUML 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 xUML 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.

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 xUML 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 xUML 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 a content type for Blob response parameters from this endpoint. This must be a valid "accept" header as defined in RFC 7231.
Refer to Handling Blobs in the REST API for a deeper explanation and some examples.

This attribute must be left unset if no Blob output parameters are used. In future versions, the effect of this attribute may be extended to other contexts as well.

a list of valid media ranges

e.g. image/png
Default is application/octet-stream if not specified.

Reject Other Response Content Types
(rejectOtherResponseContentTypes)

The xUML Runtime performs a verification of the "accept" header for REST responses. Specify whether to return an error (HTTP 406, not acceptable) on requests with an "accept" header that does not conform with the content types specified in Blob Body Content Type.
Refer to Handling Blobs in the REST API for a deeper explanation and some examples.

true

• Reject calls to the endpoint if the "accept" header does not match the values listed in Blob Body Content Type (default).

• Exception: HTTP 406 (Not acceptable)
  This exception can be suppressed by setting Ignore Http Errors to true on the REST adapter alias.

false

Accept the request in spite of the mismatch and handle this within the service.

Accepted Request Content Types
(acceptedRequestContentType)

Provide a list of content types this REST endpoint accepts. This must be a list of valid "accept" headers as defined in RFC 7231.
Refer to Handling Blobs in the REST API for a deeper explanation and some examples.

This attribute must be left unset if no Blob output parameters are used. In future versions, the effect of this attribute may be extended to other contexts as well.

a list of valid media ranges

e.g. image/png;image/jpeg
Default is application/octet-stream if not specified.

Reject Other Request Content Types
(rejectOtherRequestContentTypes)

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 API for a deeper explanation and some examples.

true

• Reject calls to this endpoint if the "content-type" header does not match the values listed in Accepted Request Content Type (default).

• Exception: HTTP 415 (Unsupported Media Type)
  This exception can be suppressed by setting Ignore Http Errors to true on the REST adapter alias.

false

Perform the adapter call in spite of the "content-type" header mismatch and handle this within the service.

In
(in)

Defines how the parameter will be passed to the REST method. This tag is mandatory.

query

via a query string

all

all simple types and Array of simple type

Unknown parameters will be ignored, known will be passed to the method after being URL-decoded.

path

via the REST resource path

all

Integer, Float, String, Boolean, DateTime

Path parameters are all required. All path parameters must be consumed by the called method and the parameter names must be the same as the path segment identifiers (without colon).

body

via the REST call body

POST, PUT, PATCH

a complex type and Array

A REST method can have only one body parameter.

header

via the REST call header

all

all simple types and Array of simple type

Unknown parameters will be ignored, known will be passed to the method.

External Name
(externalName)

Defines an external name for the REST parameter.

any string

Use this, when wanting to access a REST service that has parameter names with special characters. In this case, set this name (e.g. ugly@parameter-name) to externalName and give a better name. So you will not have to escape the parameter every time you use it.

/

If the Content-Type header is set, the xUML Runtime will assume that the request is of that type. All other request will be rejected (HTTP error code 406).

Content-Type header

406

If no Content-Type header is set, but the Accept header is, the xUML Runtime will deduce the request type from it. All other request will be rejected (HTTP error code 406).
To determine the format, the Runtime will take into account the quality factor and the order of the accept headers list.

Accept header

406

In absence of both headers, the Runtime will assume JSON. All other request will be rejected (HTTP error code 415).

JSON

415

requestOptions

RequestOptions

in

Use this parameter to configure the REST Adapter dynamically and overwrite the settings from the component diagram.

response

Any

out

This parameter holds the adapter output and is of that type that is given back by the called REST service.

getRestHttpRequest()

none

object of type Request

Returns the request details as provided by the HTTP call. Changing the request object will not have any effects.

local request = getRestHttpRequest();

getRestHttpResponse()

none

object of type Response

Set the response details to return them to the caller.

local response = getRestHttpResponse();

method

HTTPMethod

HTTP method used in call.

GET

queryString

String

Query string, if provided with the call.

status=in%20progress

queryParameters

Array of Parameter

All query parameters as an array of Parameter classes containing name/value pairs.

body

Blob

Body of the HTTP request.

path

String

Path to the REST resource.

/support/supportcases/

pathParameters

Map

All REST parameters as a map.

httpHeaderMap

Map of Entry

Header information as a map. The map contains arrays of header value strings whereas the header name is the key of the map.

• Header names are lowercase and treated case insensitive.

• Multiple headers with the same name are treated as arrays.

Refer to HTTP Header Support for more information on the standard xUML HTTP headers.

headers

Array of HeaderField

All HTTP response header fields as an array of HeaderField classes containing name/value pairs.

statusCode

Integer

The resulting HTTP status code. If not set explicitly using this object, the service returns 200 if no exception occurred, or 500 otherwise.

404

errorObject

Any

Object of the type defined with stereotype RESTError.

additionalHeaders

Array of HeaderField

All REST request header fields as an array of HeaderField classes containing name/value pairs.

options

Array of Option

Specify native cURL options as listed in Setting cURL Options on the URL Adapter.

Use one of the following syntax rules:

• values separated by ',' in one line

• values separated by ' ' in one line

• list of tagged values

ssl

SSL

Use this parameter to supply SSL information.

proxy

Proxy

Use this parameter to supply necessary proxy information.

additionalQueryParameters

Array of Parameter

Use this parameter to provide additional query parameters to the REST service call.

followRedirects

Integer

Specify here the maximum number of redirects to follow. Default value is 0 (no redirects).

any integer

basicAuth

Authentication

This parameter provides an object of type Authentication containing the user and the password.

basePath

String

Overwrite here the base path of the REST service.

a valid path, e.g. /support

host

String

Overwrite here the host running the REST service that has been defined in the component diagram.

a valid host, e.g. scheer-acme.com

port

Integer

Overwrite here the port through which the REST service is accessible.

a valid port number, e.g. 12345

protocol

String

Overwrite here the protocol through which the REST service is accessible.

http

Use the HTTP protocol to access the service (default).

https

Use the HTTPS protocol to access the service.

ignoreHttpErrors

Boolean

If true,  Default value is true.

true

HTTP error codes >= 400 will not cause an exception in the service (default). This implies, that the response body is accessible even if HTTP errors occur.

false

HTTP error codes >= 400 will cause an exception in the service.

jsonComposerOptions

ComposerOptions

Use this parameter to specify JSON composer options on the REST call. You can use these options to e.g. overwrite jsonKeepNulls from the REST alias.

Valid composer options as described below.

httpStatus

Integer

HTTP status code of the adapter call.

500

headers

Array of Header Field

body

Blob

HTTP body of HTTP response.

responseObject

Any

Response Object of the REST adapter call.

• If the adapter had an error, the responseObject is a RESTError class. It could be the default error class or a specific error class dependent on the RESTResponseDefinition dependencies and the HTTP status code.

• If the adapter call had no error, the responseObject is the same as the response output parameter.

httpHeaderMap

Map of Entry

Header information as a map. The map contains arrays of header value strings whereas the header name is the key of the map.

• Header names are lowercase and treated case insensitive.

• Multiple headers with the same name are treated as arrays.

Refer to HTTP Header Support for more information on the standard xUML HTTP headers.

Authentication

username

String

Username.

password

String

Password.

Certificate

file

String

Certificate file.

type

String

ComposerOptions

keepNulls

Boolean

Keep NULL values during JSON composing.

Entry

key

String

Key of the map entry.

value

Array of Any

List of values of the map entry. The dynamic type for httpHeaderMap is String.

HTTPMethod

enumeration

List of all valid HTTP methods

DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT

HeaderField

name

String

Name of the header field.

value

String

Value of the header field.

Option

name

String

Name of the option.

value

String

Value of the option.

Parameter

name

String

Name of the parameter.

value

String

Value of the Parameter.

Proxy

url

String

URL.

A valid URL.

type

String

authentication

Authentication

See above.

SSL

verifyPeer

String

verifyHost

String

caInfo

String

certificate

Certificate

See above.

key

Key