Implementing REST Methods

This page explains how REST methods have to be implemented so they can be called via REST requests and how different kinds of REST parameters have to be defined so they are provided to the service automatically by the xUML Runtime.

The example RESTAPI_SupportManager shows the REST implementation of a simple support case manager.

With this example, you can

• create a new support case using a POST request

• get information on support cases in general, on specific support cases, and on customers using GET requests

• mark a support case as resolved using a PUT request

• mark a support case as closed using a DELETE request

The example uses the MongoDB that comes with every PAS installation to persist the support cases.

REST Methods

With REST methods, the xUML Runtime distinct between verb methods and named methods (as described on REST API). REST methods have to be static and must have stereotype REST.

Implementing Verb Methods

Verb methods intercept requests issued directly to the resource. Verb methods can only path parameters that are defined on the parent resource(s).
With the Designer, you can implement all available HTTP methods as REST methods, as there are GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS.

The Trailing "/"

Verb methods can be in form of GET or GET/. The difference is subtle but significant. It is important to understand the difference.

Have a look at the support manager example.

• A GET with a trailing / on the URL should always return a list of resources. Issuing a GET on /support/supportcases/ is expected to return a list of existing support cases.

• A GET without trainling / o the URL should always return more general information on the resources. A GET on support/supportcases is expected to return information on the support cases in general, e.g number of support cases, list of customers afflicted, ...

Look at the verb methods implemented in the example:

Simply assign the name of an HTTP method to the REST method, and the xUML Runtime calls it on the corresponding request. Append a trailing / to the method name to make the distinction described in the note above (see GET and GET/ on resources supportcases and customer):

Find below an overview on the REST methods provided by the example:

Resource	REST Operation	Description	Stereotype Attribute httpMethod	Input	In via	Output (body)
supportcases	GET	get a support case overview	GET or blank	none		SupportCaseInfo, a complex object containing some general information on the resource. In the example, these are number of support requests and a list of customers afflicted by support cases.
	GET/	query support cases	GET or blank	none		ListOfSupportCases Output parameters should be of complex type. Arrays are allowed but not accepted by all clients, so the Compiler will throw a warning. Better wrap the array in a complex type:
				status	query
				customerName	query
	POST	create a new support request	POST	SupportCase	body	SupportCase
supportcases/<id>	GET	get a specific support case	GET or blank	id	path	SupportCase
	DELETE	close support case	DELETE	id	path	ResolveMessage
supportcases/customer/<customerID>	GET/	get all support cases of a specific customer	GET or blank	customerID	path	ListOfSupportCases (Please also see tip above.)

For more information on REST parameters, e.g. input methods, see section REST Parameters below.

Implementing Named Methods

In the context of the Designer, you can used "named methods" to facilitate modeling. Named methods are REST resources with only one method. You can implement such resources directly on the parent resource with a dedicated name, e.g. resolve in the support case manager example. To call such an method, append its name (or relativePath) to the parent resource.

Error Handling

Each REST port must have a <<RESTError>> class assigned. The xUML Runtime will use this class as output in case of error (see Defining a REST API).

In the support manager example, REST port SupportAPI has class RESTError assigned as error class:

Using function getRestHttpResponse(), you get access to the HTTP response object and can set the error details:

local response = getRestHttpResponse();
set response.responseObject = <my error object>;
set response.httpStatus = <HTTP status code>;

Assign the error object and a HTTP status code that corresponds to the error. This information will be returned via the HTTP response.

The xUML Runtime will recognize attributes as error code and/or error message under the following conditions:

• if you applied the names code and/or message to these attribute(s)

• if you applied the stereotypes REST Error Code and/or REST Error Message to these attribute(s)

In this case, Runtime error codes and/or messages will automatically by assigned to these attributes in case of error.

In the support manager example, if the API user does not provide a support case id with the REST call, the implementation is as follows:

badRequest_id

create error;
set error.code = "400"; 
set error.message = "Bad Request: id missing.";

local response = getRestHttpResponse();
set response.responseObject = error;
set response.httpStatus = 400;

REST Parameters

REST methods do not need to have parameters, but they can have. Typically, they will at least have an output parameter giving back a status or the resource content.
Parameters that are coming with the REST call are automatically provided to REST parameters of the API. Output parameters are provided to the request body.

If a parameter is not provided by the caller, it will come in as NULL or have the default value, if there is a default specified. For more information on how to specify a default, see Changing the Attributes of Data Model Elements.

• Input : Input parameters can come via path, body, query, or header of the HTTP request.

• Output: There can be no or exactly one output parameter via the response body. It has to be of complex type or of type Blob. More output parameters can be specified via the HTTP headers.

The Designer supports JSON and XML content types, whereas JSON is the default if no divergent content type is specified. For more information on the supported content types, refer to Calling the REST API.

Output: Body Parameter

The REST method can provide no or exactly one output parameter via the response body. If an output is provided via the body, this has to be of complex type or of type Blob.

Depending on the Content-Type and Accept headers, the xUML Runtime will provide the response as JSON or XML.
For more information on the supported content types, refer to Calling the REST API.

Example

Activity diagram supportcases.GET implements a GET request on a specific support case.

Parameter supportCase is a complex structure and has no stereotype applied. This defaults it to a body parameter. The output format can be JSON or XML depending on the Accept header specified in the request.
For more information on the supported content types, refer to Calling the REST API.

Output: Header Parameter

The REST method can provide multiple output parameters via the response headers. These parameters can be of simple type or array of simple type. If you do not set a header parameter that is defined for an operation, this parameter is omitted and not provided in the response headers.

Example

Activity diagram supportcases.customer.GET implements a GET request support cases of a specific customer. The support case data is provided via the response body as an array of complex type, the record count is provided via the response headers.

Parameter count is transferred via the response headers:

Input: Path Parameter

Path parameters are part of the path and, thus, part of the URL, e.g. /support/supportcases/1234. They are all required. All path parameters are automatically provided to method parameters of the service having the same name. They must be consumed by the called method and must have the same name as the path segment identifiers on the resource (without colon).

They can be of type Integer, Float, String, Boolean, and DateTime. During parsing the request they are treated as Strings and then will be converted to the types defined in the model. Conversion errors are handled by the xUML Runtime by returning a 400 response ("Bad Request.").

Example

Activity diagram supportcases.supportcase.GET shows the implementation of a path parameter. It implements a GET request on a specific support case and the support case id comes via the request URL.

Parameter id is a rest parameter that comes with the resource path. Its value is transferred automatically to the method parameter having the same name. Type conversion to types divergent to String is applied automatically by the Runtime:

As you can see from the screenshot above, parameter id has a defined input method path. That implies, that the corresponding resource has this parameter defined on its relative path.

Input: Body Parameter

Body parameters are transferred in the request body. Since there is only one body in a HTTP request, only one body-parameter can be defined for an method. Body parameters have to be of complex type or of type Blob.

To be in line with the HTTP specification, body parameters are allowed for PUT, POST and PATCH requests only.

The form of the body should correspond to the content type coming with the request. At the moment, the xUML Runtime supports application/json and text/xml content types.
For more information on the supported content types, refer to Calling the REST API.

Example

Activity diagram supportcases.POST shows the implementation of a body parameter. It implements a POST request to create a new support case and the support case data comes via the request body.

Parameter supportCase is a rest parameter of complex type that comes via the request body. Its value is transferred automatically to the method parameter. Type conversion is applied automatically by the Runtime:

The content that comes within the body (whether JSON or XML) must represent the structure given by complex type SupportCase.

Input: Query Parameter

Query parameters are provided to the service via the standard query-string. It is appended to the path after the ? delimiter and key-value pairs are delimited by &, e.g. /support/supportcases/?status=in%20progress&customerName=Wishes%20unltd .
The xUML Runtime will ignore unknown parameters, known parameters will be decoded and passed to the method. It is not necessary to provide all possible parameters with the query-string - omitted parameters will be NULL or have the specified default value (see Changing the Attributes of Data Model Elements).

Query parameters can be of any simple type (Integer, Float, String, Boolean, DateTime, and Blob) or Array. During parsing the request, these are treated as Strings and will be converted to the types defined in the model. Conversion errors will be handled by the xUML Runtime by returning a 400 response ("Bad Request.").

Arrays

Arrays are accepted, but they must be continuous arrays. A request like /my_resource?a=1&b=2&a=3&a=4 is valid and produces two parameters:

• an array of Strings a = ['1', '3', '4']

• a String b = '2'

A request like /my_resource? a[0]=1&b=2&a[5]=3&a[6]=4 is not valid.

Example

Activity diagram supportcases.GET/ shows the implementation of a query parameter. It implements a GET request on support cases by status.

Parameter status is a REST parameter that comes via the query-string. Its value is transferred automatically to the corresponding method parameter of the same name. Type conversion is applied automatically by the Runtime:

Input: Header Parameter

Header parameters are transferred through request headers. Similarly like query parameters, unrecognized items are ignored by the xUML Runtime.