Div

Class	e2e-refDiv

Otp

Floating	false

Rp
REST Adapter

Stereotype Attributes

REST Alias

Multiexcerpt

MultiExcerptName	RESTAlias

Attribute
(Name of Setting) Description Allowed Values / Examples

Name Specify a name for the alias. any string

Standard

Protocol
(protocol) Specify here the protocol through which the REST service is accessible. http, https

Port
(port) Specify here the port through which the REST service is accessible. a valid port

Host
(host) Specify here the host running the REST service. a valid host

Base Path
(basePath)

Specify here the base path of the REST service.

Info
Please note that the base path differs whether you want to access a Designer service from the outside of PAS or from the inside. When you trigger Designer services within the platform, use the part of the path starting with /rest/....

a valid path, e.g

/Idea_Management/rest/process/Idea_management if you want to access a Designer service from outside PAS
/rest/process/Idea_management if you want to access a Designer service from inside PAS

Ignore HTTP Errors
(ignoreHttpErrors)

Specify here whether you want the REST adapter to throw an exception upon receiving an HTTP error code >= 400.

true

Do not throw an exception upon receiving an HTTP error code >= 400 (default).

false Throw an exception upon receiving an HTTP error code >= 400.

Additional Request Headers
(additionalHeaders) This attribute can contain a list of additional headers in form of name/value pairs. Valid format is: <name>:<value>, e.g. API-Key:acme . Separate multiple headers with a comma.

Advanced

HTTP Header Role Definitions for requests
(requestHttpHeaderRoles)

Multiexcerpt include

SpaceWithExcerpt	INTERNAL
MultiExcerptName	requestHttpHeaderRoles
PageWithExcerpt	INTERNAL:_designer_excerpts_stereotypes

Multiexcerpt include

SpaceWithExcerpt	INTERNAL
MultiExcerptName	requestHttpHeaderRoles_adapter
PageWithExcerpt	INTERNAL:_designer_excerpts_stereotypes

client_host

Provide the client host in a header <http header name>instead of X-Sender-Host.

client_service

Provide the client service in a header <http header name> instead of X-Sender-Service.

correlation_id

Provide the correlation ID in a header <http header name> instead of X-Request-Id.

transaction_id

Provide the transaction ID in a header <http header name> instead of X-Transaction-Id.

passthrough

Pass a present header <http header name> to the called service.

passthrough=<request header name>

Pass an present header <request header name> to the called service under the name of <http header name>.
This is equivalent to renaming a header.

Digest Algorithm
(digestAlgorithm)

Multiexcerpt include

SpaceWithExcerpt	INTERNAL
MultiExcerptName	digestAlgorithm
PageWithExcerpt	INTERNAL:_designer_excerpts_stereotypes
shouldDisplayInlineCommentsInIncludes	false

None

No header generated (default).

MD5

Generate header using MD5 algorithm.

SHA

Generate header using SHA algorithm.

SHA-1

Generate header using SHA-1 algorithm.

SHA-256

Generate header using SHA-256 algorithm.

SHA-512 Generate header using SHA-512 algorithm.

Accepted Count of Redirects to Follow
(followRedirects)

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

any integer, 0 (default)

cURL O ptions
(options)

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 attributes

JSON: Keep Null Values
(jsonKeepNulls) When jsonKeepNulls is true, attributes of the REST parameter having NULL values will be provided with the REST call, otherwise they will be left out completely (see also chapter NULL Values). true Render attributes with NULL values to the REST call.

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

JSON: Compact Format
(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.

JSON: Write Type Discriminator true

false

Authentication

User
(user) Specify credentials here if the called REST service needs basic authentication. Valid format is <user>/<password>, e.g. david.stringer/pAsWoRd456

Proxy Settings (if the called REST service is accessed via a proxy)

Proxy: URL
(proxyURL) Specify the URL of the proxy server. See CURLOPT_PROXY.

Proxy: User
(proxyUser) Specify the proxy credentials. See CURLOPT_PROXYUSERPWD, format is <user>/<password>, e.g. david.stringer/pAsWoRd456

Proxy: Type
(proxyType) Specify the proxy type. See CURLOPT_PROXYTYPE.

SSL Settings (if the called REST service uses SSL)

SSL: CA Info
(sslCAInfo) Specify a file name containing additional certificates for the connection verification (e.g. additional root CAs). See CURLOPT_CAINFO.

SSL: Certificate File
(sslCertificateFile) Specify a fle name containing the client certificate. See CURLOPT_SSLCERT.

SSL: Certificate Type
(sslCertificateType) Specify the type of the certificate. See CURLOPT_SSLCERTTYPE.

SSL: Private Key File
(sslPrivateKeyFile) Specify a file name containing the private key. See CURLOPT_SSLKEY.

SSL: Private Key Password
(sslPrivateKeyPassword) Specify the password for the private key. See CURLOPT_KEYPASSWD.

SSL: Private Key Type
(sslPrivateKeyType) Specify the type of the key. See CURLOPT_SSLKEYTYPE.

SSL: Verify Host
(sslVerifyHost) Specify whether to verify the host information form the SSL connection. See CURLOPT_SSL_VERIFYHOST.

SSL: Verify Peer
(sslVerifyPeer) Specify whether to verify the peer information from the SSL connection. See CURLOPT_SSL_VERIFYPEER.

REST Adapter

Multiexcerpt

MultiExcerptName	RESTAdapter

Attribute
(Name of Setting)

Description

Allowed Values / Examples

Alias
(alias)

Specify the REST alias the adapter should use to establish the connection.

a valid REST alias

Digest Algorithm
(digestAlgorithm)

Multiexcerpt include

SpaceWithExcerpt	INTERNAL
MultiExcerptName	digestAlgorithm
PageWithExcerpt	INTERNAL:_designer_excerpts_stereotypes
shouldDisplayInlineCommentsInIncludes	false

None

No header generated (default).

MD5

Generate header using MD5 algorithm.

SHA

Generate header using SHA algorithm.

SHA-1

Generate header using SHA-1 algorithm.

SHA-256

Generate header using SHA-256 algorithm.

SHA-512

Generate header using SHA-512 algorithm.

REST API

This stereotype defines a package as a REST port. It has no additional attributes.

REST Operation

Multiexcerpt

MultiExcerptName	REST

Attribute
(Name of Setting) Description Allowed Values / Examples

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)

Multiexcerpt include

SpaceWithExcerpt	INTERNAL
MultiExcerptName	isVerbatimPath
PageWithExcerpt	INTERNAL:_designer_excerpts_stereotypes
shouldDisplayInlineCommentsInIncludes	false

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.

Info
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 valid media range

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 content-type header for REST calls. Specify whether to return an error for requests 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 "Content-Type" header does not match the value 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 Types
(acceptedRequestContentType)

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.

Info
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/jpeg;image/png
Default is application/octet-stream if not specified.

Reject Other Request Content Types
(rejectOtherRequestContentTypes)

Specify whether to return an error for responses 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 content types the service returns (Blob Body Content Type of service) 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.

REST Parameter

Multiexcerpt include

MultiExcerptName	RESTParameter
PageWithExcerpt	REST

REST Error (Class)
Anchor
restError
restError

The stereotype REST Error is used on a class to mark it as REST error class. Each REST port has a error class assigned that, in case of error, contains additional information. You can get this information using something like

Code Block
create error; set error = adapterResponse.responseObject;

if error is an object of the type indicated by this stereotype.

REST Port (Class)

Attribute	Description	Allowed Values / Examples
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. `/Services/SupportCase/SupportAPI`
path		any valid path string	path string starting with "/", e.g. `/support`
errorClass	Assigns a user-defined REST Error 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

REST Resource (Class)

Multiexcerpt include

MultiExcerptName	RESTResource
PageWithExcerpt	REST
shouldDisplayInlineCommentsInIncludes	false

REST Error Code (Property)

REST Error Code and REST Error Message are applied to one property of the REST Error class each to define that the corresponding properties contain the error code and the error message of the REST error. You cannot set REST Error Code on two properties of the same error class.

REST Error Message (Property)

REST Error Code and REST Error Message are applied to one property of the REST Error class each to define that the corresponding properties contain the error code and the error message of the REST error. You cannot set REST Error Message on two properties of the same error class.

REST Adapter Parameters

Multiexcerpt

MultiExcerptName	RESTAdapterParameters

Name	Type	Direction	Description
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.

REST Utility Functions

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

Function	Parameter	Return Value	Description	Example
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. For details see getRestHttpRequest().	local request = getRestHttpRequest();
getRestHttpResponse()	none	object of type Response	Set the response details to return them to the caller. For details see getRestHttpResponse().	local response = getRestHttpResponse();

REST Content Types

With the REST Adapter, the xUML Runtime can handle JSON or XML as content types. The 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.

Regarding response parsing, the xUML 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 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.

REST Parameter Types

AdapterResponse

Multiexcerpt

MultiExcerptName	AdapterResponse

Attribute

Type

Description

Allowed Values / Examples

httpStatus

Integer

HTTP status code of the adapter call.

500

headers

Array of HeaderField

Note

icon	false

DeprecatedThis attribute is deprecated. It is only present for compatibility reasons.

Please use httpHeaderMap (see below) for new implementations. The implementation of httpHeaderMap complies to the HTTP specification and supports multiple headers having the same name.

body

Blob

HTTP body of HTTP response. Among others, the body contains

the response Object for successful calls
an object of the RESTError class if the call has not been successful.

responseObject

Any

Response Object of the REST adapter call if the endpoint returns one (response output parameter).

Info
The response object is only returned for successful calls.

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.

Request

Attribute	Type	Description	Allowed Values / Examples
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.

RequestOptions

Multiexcerpt

MultiExcerptName	RequestOptions
shouldDisplayInlineCommentsInIncludes	false

Attribute	Type	Description	Allowed Values / Examples
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.	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).
protocol	String		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.
ignoreHttpErrors	Boolean	If true, Default value is true.	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.

Response

Attribute	Type	Description	Allowed Values / Examples
headers	Array of HeaderField	All HTTP response header fields as an array of HeaderField classes containing name/value pairs.
httpCode	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`
responseObject	Any	Response Object of the REST adapter call if the endpoint returns one (response output parameter).

Request and Response Types

Multiexcerpt

MultiExcerptName	Request_and_Response_Types
shouldDisplayInlineCommentsInIncludes	false

REST Type Attribute Type Description Allowed Values / Examples

Authentication username String Specify a username.

password String Specify a password.

Anchor

	Certificate
	Certificate

Certificate

file

String

Provide name of a certificate file.

type String Specify the type of the certificate file. One of PEM or DER.

Anchor

	ComposerOptions
	ComposerOptions

ComposerOptions

jsonKeepNulls

Boolean

Specify the handling of NULL values.

true

Keep NULL values during JSON composing.

false Do not serialize NULL values during JSON composing.

jsonCompact Boolean Specify the generated JSON format. true Serialize to JSON without pretty-printing.

false Produce a pretty JSON.

jsonWriteTypeDiscriminator Boolean Specify whether to write type information to the generated JSON. true Write a type discriminator to the generated JSON.

false Do not write a type discriminator to the generated JSON.

Entry key String Specify the key of a map entry.

value Array of Any Provide a list of values of the map entry. The dynamic type for httpHeaderMap is String.

HeaderField name String Specify the name of the header field.

value String Provide a header value.

Anchor

	Ke<
	Ke<

Key

file

String

Specify the name of the file that contains the private key.

type String Specify the type of the private key.

password String Specify the password for the private key.

Anchor

	Option
	Option

Option

name

String

Specify the name of the cURL option.

value String Provide a value.

Parameter name String Specify the name of the parameter.

value String Provide a value.

Anchor

	Proxy
	Proxy

Proxy

url

String

Specify a URL to the proxy server.

A valid URL.

type String Specify a proxy type HTTP The proxy is a HTTP proxy.

SOCKS5 The proxy is a SOCKS5 proxy.

authentication Authentication See above.

Anchor

	SSL
	SSL

SSL

verifyPeer

String

Specify whether to verify the peer information from the SSL connection.

true

Verify the peer information (default).

false Do not verify the peer information.

verifyHost String Specify whether to verify the host information from the SSL connection. On Verify the host information (default).

Off Do not verify the host information.

Existence Only check for existence of the host.

caInfo String Specify the name of the file that contains additional certificates for the connection verification.

certificate Certificate Specify the certificate information (see above).

key Key Specify the private key information (see above).

Panel

title	On this Page:

Table of Contents

Multiexcerpt include

SpaceWithExcerpt	INTERNAL
MultiExcerptName	RESTAdapter_SupportManager_Example
PageWithExcerpt	INTERNAL:_designer_examples
shouldDisplayInlineCommentsInIncludes	false

Multiexcerpt include

SpaceWithExcerpt	INTERNAL
MultiExcerptName	RESTAdapter_BlobContent_Example
PageWithExcerpt	INTERNAL:_designer_examples

Multiexcerpt include

SpaceWithExcerpt	INTERNAL
MultiExcerptName	RESTAdapter_CallProcessWithRoles_Example
PageWithExcerpt	INTERNAL:_designer_examples

Panel

title	Related Pages:

REST Adapter

Page tree

Versions Compared

Old Version 20

New Version Current

Key

Stereotype Attributes

REST Alias

REST Adapter

REST API

REST Operation

REST Parameter

REST Error (Class)
Anchor
restError
restError

REST Port (Class)

REST Resource (Class)

REST Error Code (Property)

REST Error Message (Property)

REST Adapter Parameters

REST Utility Functions

REST Content Types

REST Parameter Types

AdapterResponse

Request

RequestOptions

Response

Request and Response Types

Page tree

Page History

Versions Compared

Old Version 20

New Version Current

Key

Stereotype Attributes

REST Alias

REST Adapter

REST API

REST Operation

REST Parameter

REST Error (Class) AnchorrestErrorrestError

REST Port (Class)

REST Resource (Class)

REST Error Code (Property)

REST Error Message (Property)

REST Adapter Parameters

REST Utility Functions

REST Content Types

REST Parameter Types

AdapterResponse

Request

RequestOptions

Response

Request and Response Types

REST Error (Class)
Anchor
restError
restError