Page History

...

Multiexcerpt

MultiExcerptName	REST_Service

<<E2ERESTService>>

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

Multiexcerpt

MultiExcerptName	E2ERESTService

Tagged Value

Description

Allowed Values

port

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

tracePort

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

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

true

Enable basic authentication.

false

Disable basic authentication (default).

jsonKeepNulls

Multiexcerpt

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

true

Render attributes with NULL values to the REST response.

false

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

jsonCompact

Multiexcerpt

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

true

Generate compact JSON (default).

false

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

Multiexcerpt

MultiExcerptName	E2ERESTPortType

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. `/Services/SupportCase/SupportAPI`
path		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

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.

Multiexcerpt

MultiExcerptName	RESTResource

Tagged Value	Description	Allowed Values
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`

<<REST>>

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

Multiexcerpt

MultiExcerptName	note_RESTOperation

Note

icon	false

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

Multiexcerpt

MultiExcerptName	REST

Tagged Value Description Allowed Values

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

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

isVerbatimPath

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

Note

icon	false

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

true

Path should be treated as verbatim, path normalization is disabled.

false (default) Path should be URL encoded.

blobBodyContentType

Multiexcerpt

MultiExcerptName	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-type

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

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

Multiexcerpt

MultiExcerptName	RESTParameter

Tagged Value Description Allowed Values Allowed REST Methods Allowed Types Hints and Limitations

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.

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.

multiplicity

Defines whether the parameter is required, or not.

0..1

Parameter is not required.

Note

icon	false

Path parameters are always required.

1 Parameter is required.

<<RESTOperationTag>>

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

Multiexcerpt

MultiExcerptName	RESTOperationTag

Tagged Value	Description
name	Defines the name of the tag. This name will be displayed in the E2E REST Test Tool as a group heading.		any string
description	You can add a short description of the tag that will be displayed in the E2E REST Test Tool together with the heading.		any string
externalDocumentationDescription	You 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
externalDocumentationURL	Defines a documentation URL for this tag group.		a valid URL
order	Defines 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>>

Multiexcerpt

MultiExcerptName	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:

Code Block
local response = getRestHttpResponse(); response.responseObject = <my error object>; response.httpStatus = <a matching http error code>;

<<RESTResponseDefinition>>

Multiexcerpt

MultiExcerptName	RESTResponseDefinition

Use dependencies with stereotype <<RESTResponseDefinition>> are used to connect REST resources with REST error classes.

Tagged Value Description Allowed Values

name Specify an HTTP status code. For this status code, the default error class will be overwritten by the specific error class. a specific HTTP status code e.g. 401

a pattern e.g. 40? or 4??

all status codes ???

blobBodyContentType

Multiexcerpt include

MultiExcerptName	blobBodyContentType
PageWithExcerpt	XBRIDGE2:@self

a valid MIME-type

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

...

Multiexcerpt

MultiExcerptName	RESTAlias

Attribute Description Allowed Values

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

basePath Specify here the base path of the REST service. a valid path, e.g. /support

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

Note

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

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

host Specify here the host running the REST service. a valid host

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

followRedirects Specify 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

jsonKeepNulls Builder 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). true Render attributes with NULL values to the REST call.

false Leave out attributes with NULL values in the REST call (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. true Generate compact JSON (default).

false Generate pretty JSON.

user Specify 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)

proxyType Specify the proxy type. See CURLOPT_PROXYTYPE.

proxyURL Specify the URL of the proxy server. See CURLOPT_PROXY.

proxyUser Specify the proxy credentials. See CURLOPT_PROXYUSERPWD, valid format is <user>/<password>, e.g. e2e/e2e

SSL Settings (if the called REST service uses SSL)

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

sslCertificateFile Specify a fle name containing the client certificate. See CURLOPT_SSLCERT.

sslCertificateType Specify the type of the certificate. See CURLOPT_SSLCERTTYPE.

sslPrivateKeyFile Specify a file name containing the private key. See CURLOPT_SSLKEY.

sslPrivateKeyPassword Specify the password for the private key. See CURLOPT_KEYPASSWD.

sslPrivateKeyType Specify the type of the key. See CURLOPT_SSLKEYTYPE.

sslVerifyHost Specify whether to verify the host information form the SSL connection. See CURLOPT_SSL_VERIFYHOST.

sslVerifyPeer Specify whether to verify the peer information from the SSL connection. See CURLOPT_SSL_VERIFYPEER.

...

Multiexcerpt

MultiExcerptName	REST_Parameter_Types

Request

Attribute	Type	Description	Values/Example
method	HTTPMethod	HTTP method used in call.	`GET`
headers	Array of HeaderField	All 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.
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.

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

Multiexcerpt

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

Multiexcerpt

MultiExcerptName	AdapterResponse

Attribute	Type	Description	Values/Example
httpStatus	Integer	HTTP status code of the adapter call.	500
headers	Array of HeaderField	HTTP headers of HTTP response.
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 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 Type	Attribute	Type	Description	Values/Example
Authentication	username	String	Username.
Authentication	password	String	Password.
Certificate	file	String	Certificate file.
Certificate	type	String
ComposerOptions	keepNulls	Boolean	Keep `NULL` values during JSON composing.
HTTPMethod		enumeration	List of all valid HTTP methods	`DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT`
HeaderField	name	String	Name of the header field.
HeaderField	value	String	Value of the header field.
Option	name	String	Name of the option.
Option	value	String	Value of the option.
Parameter	name	String	Name of the parameter.
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

Page tree

Versions Compared

Old Version 1

New Version 2

Key

<<E2ERESTService>>

<<E2ERESTPortType>>

<<RESTResource>>

<<REST>>

Anchor
rest_parameter
rest_parameter
<<RESTParameter>>

<<RESTOperationTag>>

<<RESTError>>

<<RESTResponseDefinition>>

Request

Response

RequestOptions

AdapterResponse

Request and Response Types

Page tree

Page History

Versions Compared

Old Version 1

New Version 2

Key

<<E2ERESTService>>

<<E2ERESTPortType>>

<<RESTResource>>

<<REST>>

Anchorrest_parameterrest_parameter<<RESTParameter>>

<<RESTOperationTag>>

<<RESTError>>

<<RESTResponseDefinition>>

Request

Response

RequestOptions

AdapterResponse

Request and Response Types

Anchor
rest_parameter
rest_parameter
<<RESTParameter>>