Stereotype Attributes
Stereotype REST API is to used define a REST API for a Designer service. port
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. Accept unlimited requests (default of services compiled with Builder versions < 7.12.0). 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. Defines the maximum number of request that can be processed in parallel. 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. 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. Stereotype REST Port is used on a class to mark it as REST port, the root element of a REST service structure. Stereotype REST Resource is used on a class to mark it as REST resource, part of a REST service structure. Disable most of the path normalization. All escaping must be done manually, leading or trailing whitespaces are preserved. Stereotype REST is used on a REST resource class method to mark it as REST method, part of a REST service structure. If the method name is one of GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS (with optional trailing '/'), it will be invoked automatically on its parent resource when an corresponding request is received. Refer Implementing REST Methods to for more details and some examples. Provide the HTTP method of this REST method should respond to. Disable most of the path normalization. All escaping must be done manually, leading or trailing whitespaces are preserved. Specify a content type for Blob response parameters from this endpoint. This must be a valid "accept" header 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. 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. 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. 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. Stereotype REST Parameter is used on a REST method parameter to mark it as REST parameter. Refer to REST Parameters to for more details and some examples. Stereotype REST Error is used on a class to mark it as REST error class. Assign such a class to the REST port (see REST Port) and this class will be used as output in case of error. Each REST port can have its separate error class.REST API
Tagged Value Description Allowed Values 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 any positive integer 0 2048 2MB, default if not specified maxRequestHeaderSize any positive integer 8 8 KB (default if not specified). maxParallelConnections any positive integer tokenType 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 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. REST Port
Tagged Value Description Allowed Values 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/SupportAPIany valid path string path string starting with "/", e.g. /supporterrorClass 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.
For more information on REST error classes, see RESTError.any complex type describing the structure of the error apiVersion Defines the API version this port type provides (for documentation purposes only). any string REST Resource
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)
This is what still will be done, if isVerbatimPath is set to true:
The xUML Runtime will try to find and replace variables (:<my variable name>).
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).
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. REST
Attribute
(Name of Setting)Description Allowed Values Http Method
(httpMethod)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)
This is what still will be done, if isVerbatimPath is set to true:
The xUML Runtime will try to find and replace variables (:<my variable name>).
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).
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)
Refer to Handling Blobs in the REST Interface for a deeper explanation and some examples. a list of valid media ranges e.g. image/png
Default is application/octet-stream if not specified.Reject Other Response Content Types
(rejectOtherResponseContentTypes)
Refer to Handling Blobs in the REST Interface for a deeper explanation and some examples.true 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)
Refer to Handling Blobs in the REST Interface for a deeper explanation and some examples.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)
Refer to Handling Blobs in the REST Interface for a deeper explanation and some examples.true 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. REST Parameter
Tagged Value Description Allowed Values Allowed REST Methods Allowed Types Hints and Limitations 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.REST Error
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>;
REST Content Types
The xUML Runtime handles content types as follows: 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). 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). In absence of both headers, the Runtime will assume JSON. All other request will be rejected (HTTP error code 415). The full matching is done in a "best effort" manner. Given the type format Content Type Header Accept Header Runtime Behavior Assumed Content Type HTTP Header Code
(if content not matching)
/ 
Content-Type header 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 JSON 415 <type>/<subtype>[+<suffix>][; paramName=paramValue]*, the xUML Runtime first disregards the type and parameters. Then it checks, if the subtype is JSON or XML. If the subtype doesn't match with the supported types, it tries the suffix.
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 Utility Functions
Access to HTTP request and response objects is provided through global methods: getRestHttpRequest()and getRestHttpResponse(). getRestHttpRequest() returns the headers in REST service context. In other contexts, e.g. if called via a SOAP shadow port (and thus SOAP context), getRestHttpRequest() will return 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. local request = getRestHttpRequest();
getRestHttpResponse() none object of type Response Set the response details to return them to the caller. local response = getRestHttpResponse();
NULL. Use getServiceContext() or getServiceContextValue() in such cases.
REST Parameter Types
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. Specify native cURL options as listed in Setting cURL Options on the URL Adapter. Use one of the following syntax rules: Response Object of the REST adapter call. 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
Attribute Type Description Values/Example method HTTPMethod HTTP method used in call. GETqueryString String Query string, if provided with the call. status=in%20progressqueryParameters 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
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. 404errorObject 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 ',' in one line' ' in one linessl 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. /supporthost 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 headers Array of Header Field body Blob HTTP body of HTTP response. responseObject Any httpHeaderMap Map of Entry 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, PUTHeaderField 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
On this Page:
RESTAPI_SupportManager_Example
 |
Click the icon to download a simple example model that shows the implementation of a REST API with Scheer PAS Designer. |
RESTAPI_BlobContent_Example
|
Click the icon to download a simple example model that shows the implementation of a REST API that receives and returns Blob content with Scheer PAS Designer. |
Related Documentation:
Overview
Content Tools