Stereotype Attributes
RESTAlias
Attribute (Name of Setting) | Description | Allowed Values | |
---|---|---|---|
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. 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
| |
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. | |
HTTP Header Role Definitions for Requests (requestHttpHeaderRoles) | In the context of HTTP based adapters (URL, REST, SOAP), enable automatic header generation for the listed headers. These definitions overwrite the default behavior, and X-Transaction-Id, X-Request-Id, X-Sender-Host and/or X-Sender-Service will be substituted by this definition. requestHttpHeaderRoles can hold a list of definitions in format | client_host | Provide the client host in a header <http header name> |
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. | ||
Algorithm (digestAlgorithm) | Generates a HTTP digest header using the specified algorithm. When applied, a digest header is generated using the specified algorithm, and sent with the request. The generated header conforms with RFC3230 and RFC5843. Only one value is supported (no multi-value header). | 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 Options (options) | Specify native cURL options as listed in Setting cURL Options on the URL Adapter. Use one of the following syntax rules:
| ||
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. | ||
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. |
RESTAdapter
Attribute (Name of Setting) | Description | Allowed Values | |
---|---|---|---|
Alias (alias) | Specify the REST alias the adapter should connect to. | a valid REST alias | |
Digest Algorithm (digestAlgorithm) | Generates a HTTP digest header using the specified algorithm. When applied, a digest header is generated using the specified algorithm, and sent with the request. The generated header conforms with RFC3230 and RFC5843. Only one value is supported (no multi-value header). | 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. |
RESTInterface
This stereotype defines a package as REST interface. It has no additional attributes.
RESTResource
Attribute (Name of Setting) | Description | Allowed Values | |
---|---|---|---|
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.
| true | Path should be treated as verbatim, path normalization is disabled. |
false (default) | Path should be URL encoded. |
RESTOperation
Attribute (Name of Setting) | 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 |
| ||
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.
| 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 default content type for Blob response parameters from this endpoint. This must be a list of valid Accept headers as defined in RFC 7231. 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. application/msexcel 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 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. | true |
|
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 this REST endpoint accepts. This must be a list of valid Accept headers as defined in RFC 7231. 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. application/xhtml+xml 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. | true |
|
false | Perform the adapter call in spite of accept header mismatch and let the service handle this. |
RESTParameter
Attribute (Name of Setting) | Description | Allowed Values | |
---|---|---|---|
External Name (externalName) | Defines an external name for the REST parameter | any string | |
In (in) | Defines how the parameter will be passed to the REST method. This attribute is mandatory. | query | via a query string |
path | via the REST resource path | ||
body | via the REST call body | ||
header | via the REST call header |
REST Adapter Parameters
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 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
Request
Attribute | Type | Description | Values/Example |
---|---|---|---|
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.
Refer to HTTP Header Support for more information on the standard xUML HTTP headers. |
Response
Attribute | Type | Description | Values/Example |
---|---|---|---|
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>>. |
RequestOptions
Attribute | Type | Description | Values/Example |
---|---|---|---|
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:
| |
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. | |
port | Integer | Overwrite here the port through which the REST service is accessible. | |
protocol | String | Overwrite here the protocol through which the REST service is accessible. | http, https |
ignoreHttpErrors | Boolean | If true, HTTP error codes >= 400 will not cause an exception in the model. This implies, that the response body is accessible even if HTTP errors occur. Default value is true. | true / false |
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. |
AdapterResponse
Attribute | Type | Description | Values/Example |
---|---|---|---|
httpStatus | Integer | HTTP status code of the adapter call. | 500 |
body | Blob | HTTP body of HTTP response. | |
responseObject | Any | Response Object of the REST adapter call.
| |
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.
Refer to HTTP Header Support for more information on the standard xUML HTTP headers. |
Request and Response Types
REST Type | Attribute | Type | Description | Values/Example |
---|---|---|---|---|
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 |