Page History
Wanting to implement a REST API to a Designer service, you first have to figure out the resource structure. Have a look at the structure of the REST example:
The rest interface SupportAPI has the following structure:
| Resource | Methods | |
|---|---|---|
| supportcases that accept GET, GET/ and POST. | GET | Get some information on the existing support cases. |
| GET/ | Get all support cases. | |
| POST | Create a new support case. | |
| A single supportcase resource (below supportcases) that can be accessed via an id. | DELETE | Close a support case. |
| GET | Get the data of a single support case. | |
| GET (resolve) | Set the status of the support case to "resolved". | |
| A customer resource (below supportcases) that can be accessed via a customerID. | GET/ | Get all support cases of that specific customer. |
From the example, you can see implementations of GET, POST and DELETE methods. Of course, you can use the other available methods with the Designer, as there are PUT, PATCH, HEAD and OPTIONS.
| Info |
|---|
REST resources are generated to the OpenAPI file with their class name only, instead of their fully qualified name (including the xUML package structure, like |
| Info |
|---|
You can add multiple REST APIs to a Designer service. |
| Panel | ||
|---|---|---|
| ||
|
| Panel | ||
|---|---|---|
|
| Otp | ||||
|---|---|---|---|---|
|
Defining a REST Port
Once you have created a REST API to your Designer service, you can add a REST port. A REST port is a class having the stereotype REST Port.
| Info |
|---|
You can add multiple REST ports to the same REST API. |
Example
The REST port SupportAPI has path /support applied. The REST API can be accessed via /support instead of /API/SupportCase/SupportAPI as depicted in the service panel below.
The REST port has class RESTError applied as REST error class.
Defining Resources
A REST resource is a class having the stereotype REST Resource. This stereotype represents both: collections of resources (e.g. supportcases) and single resources (supportcase). Both are handled indifferently by the Designer. It is the modeler who should be aware, that some methods may not make sense on collections.
REST Resources have the following stereotype attributes:
| Multiexcerpt include | ||||
|---|---|---|---|---|
|
Example
| Example REST Resource | Description | |
|---|---|---|
| supportcases |
| REST resource supportcases has no relative path applied. It will be accessible via /support/supportcases. The first part of the URL is coming from the path value of the REST port. |
| supportcase |
| REST resource supportcase has a dynamic path applied: :id. The colon indicates that this path segment is a parameter. id must be a REST parameter and accepted by all REST operations related to this resource. For more information on REST parameters refer to Defining REST Parameters. |
| customer |
| REST resource customer has a combined static and dynamic path applied: customer/:customerID. This is necessary to avoid conflicts with supportcase, which also has dynamic elements in its path. |
Defining REST Methods
A REST methodis an method having the stereotype REST. REST methods must be static. With REST methods, we distinct between verb methods and named methods.
- Verb Methods
Verb-methods intercept requests issued directly to the resource. Unlike named methods, verb-methods cannot specify path parameters other than the ones defined by the parent resource(s).
With the Designer, you can use all available HTTP methods, as there are GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS.
Example: AGETon /support/supportcases will route to the GET method of class supportcases and give an overview on the existing support cases. - Named Methods
To call such method, append its name (or relativePath) to the parent resource.
Example: APUTon/support/supportcases/1234/resolvewill route to the resolve method of class supportcases.
| Info | ||||
|---|---|---|---|---|
| ||||
Verb methods (unlike normal methods) can be in form of Think about the support manager example.
|
REST methods have the following stereotype attributes:
| Multiexcerpt include | ||||
|---|---|---|---|---|
|
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.
Examples
| Example REST Resource | Method | Description | |
|---|---|---|---|
| GET and GET/ | verb method | Both methods have no httpMethod applied as GET is the default method. They will be invoked, when accessed via a GET on /support/supportcases or /support/supportcases/. |
| POST | verb method | This method has httpMethod POST applied. It will be invoked on a POST on /support/supportcases. | |
| DELETE | verb method | This method has httpMethod DELETE applied. It will be invoked, when accessed via a DELETE on /support/supportcases/<a support case id>, because its parent resource has a relative path :id applied. |
| GET | verb method | This method has no httpMethod applied as GET is the default method. It will be invoked, when accessed via a GET on /support/supportcases/<a support case id>. | |
| resolve | named method | This method has httpMethod PUT applied. It will be invoked, when accessed via a PUT on /support/supportcases/<a support case id>/resolve. | |
| GET/ | verb method | This method has no httpMethod applied as GET is the default method. It will be invoked, when accessed via a GET on /support/supportcases/customer/<a customer id>, because its parent resource has a relative path :customerID applied. |
Defining REST Parameters
A REST parameter is an input parameter of a REST method having the stereotype REST Parameter. This defines that this parameter will be provided via path, query, body, or header of the HTTP request. This has to be indicated on the parameter by setting stereotype attributes in:
| Multiexcerpt include | ||||||
|---|---|---|---|---|---|---|
|
All path parameters are required.
Examples
| Example REST Resource | REST Parameter | Attribute "in" | Remark |
|---|---|---|---|
| status, customerName | query | status and customerName are provided via the query string: /support/supportcases/?status=in%20progress. In this case, the xUML Runtime will automatically assign the parameter values coming with the query string to the REST parameters. |
| supportCase | body | For posting a new support case, the support case data supportCase is provided through the HTTP body. In this case, the xUML Runtime will automatically assign the data from the embodied JSON or XML document to the REST parameter class. | |
| id | path | REST resource supportcase has a dynamic path :id applied. For this reason, all methods of this resource must have a REST parameter with the same name id that will receive the value from the URL. |
REST Errors
| Multiexcerpt | ||
|---|---|---|
| ||
REST services in general return errors via the HTTP status code, so first of all, you should carefully choose the status code you are returning on a service call. Besides the HTTP status code there is no standard way of how to provide additional error information with standard REST service implementations. Developers can return additional information in HTTP headers or body, though. With the Designer REST implementation, we decided to provide error information via the HTTP body by an error class or a Blob. |
| Multiexcerpt | |||||
|---|---|---|---|---|---|
| |||||
Each REST port type must have a default <<RESTError>> class assigned. The xUML Runtime will use this class as a default output in case of error.
In case of error, this class should be
Refer to Implementing REST Operations for more information on error handling. |
Overview
Content Tools