| 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
(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. | Trace Port
(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 Bridge 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 Bridge 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 Bridge 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 |
| 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 |
Max Request Body Size
(maxRequestBodySize) | | Multiexcerpt include |
|---|
| SpaceWithExcerpt | INTERNAL |
|---|
| MultiExcerptName | max_request_body_size |
|---|
| PageWithExcerpt | INTERNAL:_bridge_excerpts |
|---|
|
| any positive integer | | 0 | accept unlimited requests (default of services compiled with Builder versions < 7.12.0) | | 2048 | Builder 7.12.0 2MiB, default if not specified | Http Header Roles
(httpHeaderRoles) | Builder 7.12.0 Runtime 2020.12 Assign roles to dedicated incoming headers that define how the related header will be treated by the xUML Runtime. These definitions overwrite the default behavior (see REST Adapter > HTTP Headers), and X-Transaction-Id, X-Request-Id, X-Sender-Host and/or X-Sender-Service will be substituted by this definition. Refer to HTTP Header Support > Overwriting the Standard HTTP Headers for more details. Http Header Roles can hold a list of definitions in format <http header name>:<role>, where <role> can be one of the listed allowed values (one list entry per line). | client_host | Take the sender host from header <http header name> instead of X-Sender-Host. | client_service | Take the sender service from header <http header name> instead of X-Sender-Service. | correlation_id | Take the correlation ID from header <http header name> instead of X-Request-Id. | transaction_id | Take the transaction ID from header <http header name> instead of X-Transaction-Id. | Token Type
(tokenType) | Mark the service as to use token authorization. The Bridge 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. | Token Header Name
(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). | Use Basic Auth
(useBasicAuth) | Mark the service as to use basic authentication mechanisms. The Bridge 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). | Json Keep Nulls
(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). | Json Compact
(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
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 | RESTResourceE2ERESTPortType |
|---|
|
| Tagged Value | Description | Allowed Values | relativePath
|---|
Path
(path) | 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.to this rest interface. If empty, the path is derived from the package structure. | none | path of the package structure | none | the name of the REST resource will be used, e.g. /Services/supportcasesSupportCase/SupportAPI | | any valid path 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 methodspath string starting with "/", 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 |
|---|
|
| Info |
|---|
| <<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.
/support | Error Class
(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 | Api Version
(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 |
|---|
|
| Multiexcerpt |
|---|
|
|
| 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.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 |
|
<<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 |
|---|
|
|
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>> 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 |
|---|
|
| Tagged Value | 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 | - 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) | Disable most of the path normalization. All escaping must be done manually, leading or trailing whitespaces are preserved. | Info |
|---|
| 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. | Blob Body Content Type
(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 |
|---|
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. | 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. | Multiplicity
(multiplicity) | Defines whether the parameter is required, or not. | 0..1 | Parameter is not required. | Info |
|---|
| 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 |
|---|
|
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. | Info |
|---|
| 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 | Allowed Values | | name | Defines the name of the tag. This name will be displayed in the Bridge 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 Bridge 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 | 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. |
...