Page History
...
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. | |
Underneath the supportcases, there is a single supportcase that can be accessed via its id. | DELETE | Close a support case. |
GET | Get the data of a single support case. | |
resolve | Set the status of the support case to "resolved". | |
Underneath the supportcases as well, there is a customer that can be accessed via its 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 E2E Bridge, 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 |
Defining the REST Port Type
A REST Port Type is a class having stereotype <<E2ERESTPortType>>. A REST port type can be deployed just like any other E2E xUML service. It has the following tagged values:
...
Note the trace port that can be defined on the <<RESTService>> component. This is a shadow SOAP port that can be used to test the REST methods with the E2E Analyzer.
Example
The <<E2ERESTPortType>> SupportAPI has path /support
applied. The REST service can be accessed via /support
instead of /Services/SupportCase/SupportAPI
as depicted in the containment tree below.
...
Multiexcerpt include MultiExcerptName RESTResource PageWithExcerpt REST
Examples
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 type. | |
supportcase | REST resource supportcase has a dynamic path applied: :id. It will be accessible via 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 Method is an method having the stereotype <<REST>>. REST methods must be static.
...
- 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 E2E Bridge, you can use all available HTTP methods, as there are GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS.
Example: AGET
on /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: APUT
on/support/supportcases/1234/resolve
will route to the resolve method of class supportcases.
Noteinfo | ||||
---|---|---|---|---|
| ||||
Verb methods (unlike normal methods) can be in form of Think about the support manager example.
|
...
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 | Descripton | |
---|---|---|---|
supportcases | 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/ . |
getByDate | named method | This method has httpMethod GET applied. It will be invoked on a GET on /support/supportcases/date=<a valid date> . | |
POST | verb method | This method has httpMethod POST applied. It will be invoked on a POST on /support/supportcases . | |
supportcase | 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 . | |
customer | 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 <<RESTParameter>>. 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 tagged value in:
...
All path parameters are required. For all other parameters, use the multiplicity to specify whether they are required or not.
Examples
Example REST Resource | REST Parameter | Tagged Value "in" | Remark |
---|---|---|---|
supportcases | 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 parameters 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. | |||
supportcase | 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 REST service implementations. Developers can return additional information in HTTP headers or body, though. With the E2E Bridge REST implementation, we decided to provide error information via the HTTP body by an error class or a Blob (Bridge 7.1.0). |
Multiexcerpt | ||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||||||||||||
Default Error ClassEach REST port type should have a default <<RESTError>> class assigned. The E2E Bridge will use this class as a default output in case of error. Figure: Example REST Error Class In case of error, this class should be
Refer to Implementing REST Operations for more information on error handling. Specific Error ClassesYou can define specific error classes for specific HTTP errors to provide more information on the error, or just return a Blob. Figure: Specific Error Class
There is no difference between using an error class or a Blob. Assign the specific error class to related operations or REST resources via a <<use>> dependency having stereotype <<RESTResponseDefinition>>. Figure: Assigning Error Class to REST Operations On these <<use>> dependencies, you have to specify an HTTP status code on the name tag. For this status code, the default error class will be overwritten by the specific class.
You can apply the following name templates:
The definitions above are reflected in the OpenAPI service description (see REST Response Definitions).
Bridge 7.1.0 For responses of type Blob, you can additionally specify a blob body content type on the <<RESTResponseDefinition>> (tag blobBodyContentType). This information will be generated to the OpenAPI descriptor file and will set the the "Content-Type" header to this content type. Default content type is "application/octet-stream". Refer to Implementing REST Operations for more information on error handling. |
REST Interface Documentation and Tags
Documenting REST Operations
When compiling a REST service, an OpenAPI descriptor file is created that contains the service description. This file reflects the REST interface structure as implemented by you.
Note | ||
---|---|---|
| ||
REST resources are generated with their class name only, instead of their fully qualified name (including the xUML package structure, like |
The generated OpenAPI file also contains textual documentation. You can add this textual documentation to the following model elements:
- REST port type
- REST method
- method parameters
- REST error class
Figure: Specification Dialog of a REST Method
The documentation from the model elements will be added to the description and summary tag of the service descriptor:
Panel | ||||
---|---|---|---|---|
| ||||
swagger: '2.0' basePath: /support [...] paths: [...] /supportcases/: get: summary: Query support cases by status and customer name. description: Query support cases by status and customer name. parameters: - name: status in: query description: (_Optional_) Status the selected support cases should be in. type: string required: false - name: customerName in: query description: (_Optional_) Name of the customer who's support cases should be selected. type: string required: false responses: 200: description: A list of support cases that correspond to the query. schema: title: supportCases $ref: '#/definitions/urn:Services.SupportCase.Classes.ListOfSupportCases' default: description: "400 - Logical error, Bad Request / \n404 - Technical error,\ \ Not Found / \n500 - Technical error / \n\_\n(See message string for\ \ error details.)\n" schema: $ref: '#/definitions/urn:Services.SupportCase.Classes.RESTError' [...] |
While writing the documentation, you can use plain text or Git flavored markdown. Do not use HTML mode in MagicDraw while adding documentation.
Tools supporting OpenAPI descriptor files (yaml format) can make the documentation visible:
Tagging REST Operations
You can use <<RESTOperationTag>> to group your operations. The E2E REST Test Tool will then display the operations in groups by tag. Operations without a tag assigned will appear under group "default".
Figure: REST Operation Groups
At the very bottom you can also find the base URL and the API version.
To tag a REST operation, create a new <<RESTOperationTag>> and draw a class diagram to connect it to operations via a <<use>> dependency.
Figure: Tagging REST Operations
Artifact <<RESTOperationTag>> has the following tagged values:
Multiexcerpt include | ||||
---|---|---|---|---|
|
For a better overview, we recommend to put all tag definitions in a separate package and to create a separate class diagram for each tag:
REST Response Definitions
All (default and specific) error classes are reflected in the OpenAPI file of the service as responses.
Panel | ||||
---|---|---|---|---|
| ||||
swagger: '2.0' [...] /supportcases/{id}: delete: description: Close a specific support case. parameters: - in: path name: id required: true type: string responses: '200': description: '' schema: $ref: '#/definitions/ResolveMessage' '401': description: |- - 401 - Unauthorized - 404 - Technical error, Not Found (See message string and additionalInfo for error details.) schema: $ref: '#/definitions/RESTErrorPlus' default: description: |- - 400 - Logical error, Bad Request - 404 - Technical error, Not Found - 500 - Technical error (See message string for error details.) schema: $ref: '#/definitions/RESTError' summary: Close a specific support case. tags: - Transition Support Case [...] |
In the example OpenAPI file above you can find three responses for operation delete. The responses are sorted by HTTP status code.
Status Code | Description | Response Class |
---|---|---|
200 | normal response | ResolveMessage (REST Parameter) |
401 | specific error response for authorization errors | RESTErrorPlus |
default | default error response | RESTError |
The E2E OpenAPI Importer will import these definitions to the calling service as defined in the OpenAPI file.
Note | ||
---|---|---|
| ||
. |