Page tree
Skip to end of metadata
Go to start of metadata

Tagged Values

<<E2ERESTService>>

Stereotype <<E2ERESTService>> is used in the component diagram to mark a service as REST service.

Tagged ValueDescriptionAllowed Values
portDefines the machine port number the service is binding to. This port number can be given at service level only.any number
Using ports below 1024 may require additional privileges.
tracePortDefines the shadow port of the service used for tracing.any number (default is service port + 40000)
tokenType

Mark the service as to use token authorization. The E2E REST Test Tool 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.

noneDo not use token authorization.
API KeyUse API key authorization.
tokenHeaderNameDefines 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 E2E 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 E2E REST Test Tool 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.

trueEnable basic authentication.
falseDisable basic authentication (default).
jsonKeepNulls
Builder 6.0.26 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).
trueRender attributes with NULL values to the REST response.
falseLeave out attributes with NULL values in the REST response (default).
jsonCompact
Builder 7.0.0-beta3 When jsonCompact is true, the JSON composer will generate compact JSON, otherwise it will generate pretty JSON. jsonCompact defaults to true - also on re-compile of an older model with Builder as of 7.0.0-beta3.
trueGenerate compact JSON (default).
falseGenerate pretty JSON.

<<E2ERESTPortType>>

Stereotype <<E2ERESTPortType>> is used on a class to mark it as REST port type, the root element of a REST service structure.

Tagged ValueDescriptionAllowed Values
pathDefines the path to this rest interface. If empty, the path is derived from the package structure.nonepath of the package structure will be used, e.g. /Services/SupportCase/SupportAPI
any valid path stringpath string starting with "/", e.g. /support
errorClassAssigns 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
apiVersionDefines the API version this port type provides (for documentation purposes only).any string

For more information on REST error classes, see <<RESTError>>.

<<RESTResource>>

Stereotype <<RESTResource>> is used on a class to mark it as REST resource, part of a REST service structure.

Tagged ValueDescriptionAllowed Values
relativePathDefines 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.nonethe name of the REST resource will be used, e.g. /supportcases
any valid stringthe given name will be used
a dynamic path supplying a REST parameterdynamic path, the value of the REST parameter will be passed to the REST methods, e.g. :id

<<REST>>

Stereotype <<REST>> is used on a <<RESTResource>> class method to mark it as REST method, part of a REST service structure.

<<REST>> is the stereotype to apply to a REST method. Do not confuse with <<RESTOperation>>, which is used for RESTful HTTP services as described on RESTful HTTP Service.
The latter approach is recommended only, if you want to use content types different to JSON and XML.

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.

Tagged ValueDescriptionAllowed Values
httpMethod

Provide the HTTP method of this REST method should respond to.

a valid HTTP methodGET, 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
relativePathDefines the path of the REST method in relation to the parent resource.noneThe name of the REST method will be used.
any valid stringThe 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>.
isVerbatimPath

Disable most of the path normalization. All escaping must be done manually, leading or trailing whitespaces are preserved.

This a REST Adapter setting and has no effect on REST service.

truePath should be treated as verbatim, path normalization is disabled.
false (default)Path should be URL encoded.
blobBodyContentType
Bridge 7.1.0 Specify a default content type for Blob parameters from this endpoint.
This information will be generated to the OpenAPI descriptor file and will will set the the "Content-Type" header to this content type.
a valid MIME-typee.g. application/msexcel
Default is application/octet-stream if not specified.

<<RESTParameter>>

Stereotype <<RESTParameter>> is used on a <<REST>> method parameter to mark it as REST parameter. Refer to REST Parameters to for more details and some examples.

Tagged ValueDescriptionAllowed ValuesAllowed REST MethodsAllowed TypesHints and Limitations
externalNameDefines an external name for the REST parameterany stringUse 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.
inDefines how the parameter will be passed to the REST method. This tag is mandatory.queryvia a query stringallall simple types and Array of simple typeUnknown parameters will be ignored, known will be passed to the method after being URL-decoded.
pathvia the REST resource pathallInteger, Float, String, Boolean, DateTimePath 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).
bodyvia the REST call bodyPOST, PUT, PATCHa complex type and ArrayA REST method can have only one body parameter.
headervia the REST call headerallall simple types and Array of simple typeUnknown parameters will be ignored, known will be passed to the method.
multiplicityDefines whether the parameter is required, or not.0..1

Parameter is not required.

Path parameters are always required.

1Parameter is required.

<<RESTOperationTag>>

With <<RESTOperationTag>> you can group your REST methods. Refer to Tagging REST Operations for more details.

Tagged ValueDescription
Allowed Values
nameDefines the name of the tag. This name will be displayed in the E2E REST Test Tool as a group heading.any string
descriptionYou can add a short description of the tag that will be displayed in the E2E REST Test Tool together with the heading.any string
externalDocumentationDescriptionYou can add a short description of the documentation.These field values will be generated to the OpenAPI descriptor, but are not displayed on the Test UI at the moment.any string
externalDocumentationURLDefines a documentation URL for this tag group.a valid URL
orderDefines the order in which the tag groups will be displayed on the screen. Tag groups with empty order will be displayed last.any number

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

Tagged ValueDescriptionAllowed Values
nameSpecify an HTTP status code. For this status code, the default error class will be overwritten by the specific error class.a specific HTTP status codee.g. 401
a patterne.g. 40? or 4??
all status codes???
blobBodyContentTypeBridge 7.1.0 Specify a default content type for Blob parameters from this endpoint.
This information will be generated to the OpenAPI descriptor file and will will set the the "Content-Type" header to this content type.
a valid MIME-typee.g. application/msexcel
Default is application/octet-stream if not specified.

<<RESTAlias>>

AttributeDescriptionAllowed Values
additionalHeadersThis tagged value can contain a list of additional headers in form of name/value pairs.Valid format is: <name>:<value>, e.g. API-Key:e2e. Separate multiple headers with a comma.
basePathSpecify here the base path of the REST service.a valid path, e.g. /support
protocolSpecify here the protocol through which the REST service is accessible.http, https
ignoreHttpErrors

Specify here whether you want the REST adapter to throw an exception upon receiving an HTTP error code >= 400.
For older models, if this flag is not present, it will be considered false.

ignoreHttpErrors can be overridden via the request options (see Setting REST Request Options).

true (default)Do not throw an exception upon receiving an HTTP error code >= 400.
falseThrow an exception upon receiving an HTTP error code >= 400.
hostSpecify here the host running the REST service.a valid host
portSpecify here the port through which the REST service is accessible.a valid port
followRedirectsSpecify here the maximum number of redirects to follow. Default value is 0 (no redirects).any integer
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 tagged values

jsonKeepNullsBuilder 6.0.26 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).trueRender attributes with NULL values to the REST call.
falseLeave out attributes with NULL values in the REST call (default).
jsonCompactBuilder 7.0.0-beta3 When jsonCompact is true, the JSON composer will generate compact JSON, otherwise it will generate pretty JSON. jsonCompact defaults to true - also on re-compile of an older model with Builder as of 7.0.0-beta3.trueGenerate compact JSON (default).
falseGenerate pretty JSON.
userSpecify credentials here, if the called REST service needs basic authentication. Other authentication algorithms have to be implemented manually via HTTP headers (see additionalHeaders and Setting REST Request Options).Valid format is <user>/<password>, e.g. e2e/e2e
Proxy Settings (if the called REST service is accessed via a proxy)
proxyTypeSpecify the proxy type.See CURLOPT_PROXYTYPE.
proxyURLSpecify the URL of the proxy server.See CURLOPT_PROXY.
proxyUserSpecify the proxy credentials.See CURLOPT_PROXYUSERPWD, valid format is <user>/<password>, e.g. e2e/e2e
SSL Settings (if the called REST service uses SSL)
sslCAInfoSpecify a file name containing additional certificates for the connection verification (e.g. additional root CAs).See CURLOPT_CAINFO.
sslCertificateFileSpecify a fle name containing the client certificate.See CURLOPT_SSLCERT.
sslCertificateTypeSpecify the type of the certificate.See CURLOPT_SSLCERTTYPE.
sslPrivateKeyFileSpecify a file name containing the private key.See CURLOPT_SSLKEY.
sslPrivateKeyPasswordSpecify the password for the private key.See CURLOPT_KEYPASSWD.
sslPrivateKeyTypeSpecify the type of the key.See CURLOPT_SSLKEYTYPE.
sslVerifyHostSpecify whether to verify the host information form the SSL connection.See CURLOPT_SSL_VERIFYHOST.
sslVerifyPeerSpecify whether to verify the peer information from the SSL connection.See CURLOPT_SSL_VERIFYPEER.

REST Content Types

The E2E Bridge handles content types as follows:

  • If the Content-Type header is set, the Bridge 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 Bridge will deduce the request type from it. All other request will be rejected (HTTP error code 406).
    To determine the format, the Bridge will take into account the quality factor and the order of the accept headers list.
  • In absence of both headers, the Bridge 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 <type>/<subtype>[+<suffix>][; paramName=paramValue]*, the Bridge 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

NameTypeDirectionDescription
requestOptionsRequestOptionsinUse this parameter to configure the REST Adapter dynamically and overwrite the settings from the component diagram.
responseAnyoutThis 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().

FunctionParameterReturn ValueDescriptionExample
getRestHttpRequest()noneobject of type RequestReturns the request details as provided by the HTTP call. Changing the request object will not have any effects.
local request = getRestHttpRequest();
getRestHttpResponse()noneobject of type ResponseSet the response details to return them to the caller.
local response = getRestHttpResponse();

getRestHttpRequest() will contain 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 NULL. Use  getServiceContext() or getServiceContextValue() in such cases.

REST Parameter Types

Request

AttributeTypeDescriptionValues/Example
methodHTTPMethodHTTP method used in call.GET
headersArray of HeaderFieldAll HTTP request header fields as an array of HeaderField classes containing name/value pairs. The header fields contain the standard HTTP headers as well as header parameters, if provided.
queryStringStringQuery string, if provided with the call.status=in%20progress
queryParametersArray of ParameterAll query parameters as an array of Parameter classes containing name/value pairs.
bodyBlobBody of the HTTP request.
pathStringPath to the REST resource./support/supportcases/
pathParametersMapAll REST parameters as a map.

Response

AttributeTypeDescriptionValues/Example
headersArray of HeaderFieldAll HTTP response header fields as an array of HeaderField classes containing name/value pairs.
statusCodeIntegerThe resulting HTTP status code. If not set explicitly using this object, the service returns 200 if no exception occurred, or 500 otherwise.404
errorObjectAnyObject of the type defined with stereotype <<RESTError>>.

RequestOptions

AttributeTypeDescriptionValues/Example
additionalHeadersArray of HeaderFieldAll REST request header fields as an array of HeaderField classes containing name/value pairs.
optionsArray 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

sslSSLUse this parameter to supply SSL information.
proxyProxyUse this parameter to supply necessary proxy information.
additionalQueryParametersArray of Parameter Use this parameter to provide additional query parameters to the REST service call.
followRedirectsIntegerSpecify here the maximum number of redirects to follow.any integer
basicAuthAuthenticationThis parameter provides an object of type Authentication containing the user and the password.
basePathStringOverwrite here the base path of the REST service.a valid path, e.g. /support
hostStringOverwrite here the host running the REST service that has been defined in the component diagram.
portIntegerOverwrite here the port through which the REST service is accessible.
protocolStringOverwrite here the protocol through which the REST service is accessible.http, https
ignoreHttpErrorsBooleanIf 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
jsonComposerOptionsComposerOptionsUse 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

AttributeTypeDescriptionValues/Example
httpStatusIntegerHTTP status code of the adapter call.500
headersArray of HeaderFieldHTTP headers of HTTP response.
bodyBlobHTTP body of HTTP response.
responseObjectAny

Response Object of the REST adapter call.

  • If the adapter had an error, the responseObject is an <<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.

Request and Response Types

REST TypeAttributeTypeDescriptionValues/Example
AuthenticationusernameStringUsername.
passwordStringPassword.
CertificatefileStringCertificate file.
typeString

ComposerOptionskeepNullsBooleanKeep NULL values during JSON composing.
HTTPMethod
enumerationList of all valid HTTP methodsDELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT
HeaderFieldnameStringName of the header field.
valueStringValue of the header field.
OptionnameStringName of the option.
valueStringValue of the option.
ParameternameStringName of the parameter.
valueStringValue of the Parameter.
ProxyurlStringURL.A valid URL.
typeString

authenticationAuthenticationSee above.
SSLverifyPeerString

verifyHostString

caInfoString

certificateCertificateSee above.
keyKey

  • No labels