Wanting to implement a REST interface to a service, you first have to figure out the resource structure. Have a look at the structure of the rest example:

Figure: Example Class Diagram of a REST Interface

Image Modified

The rest interface SupportAPI has the following structure:

From the example, you can see implementations of GET, POST and DELETE methods. Of course, you can use the other available methods with the Bridge, as there are PUT, PATCH, HEAD and OPTIONS.

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 xUML service. It has the following tagged values:

The REST port type can be added to the component diagram just as any other port type, e.g. SOAP port type:

Image Modified

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

Example

Image Modified

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.

Image Modified

It has a <<RESTError>> class RESTError applied as error class.

Defining REST Resources

A REST Resource is a class having stereotype <<RESTResource>>. This stereotype represents both: collections of resources (e.g. supportcases) and single resources (supportcase). Both are handled indifferently by the Bridge. It is the modeler who should be aware, that some methods may not make sense on collections.

REST Resources have the following tagged values:

Examples

Example REST Resource		Description
supportcases	Image Modified	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	Image Modified	REST resource supportcase has a dynamic path applied: :id. It will be accessible via /support/supportcases/<a specific id>, e.g. /support/supportcase/1234. 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	Image Modified	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. This resource will be accessible via /support/supportcases/customer/<a specific customer id>, e.g. /support/supportcases/customer/0815. customerID 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.

Defining REST Methods

A REST Method is 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 Bridge, you can use all available HTTP methods, as there are GET, POST, PUT, DELETE, PATCH, HEAD, and OPTIONS.
  Example: A GET 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: A PUT on /support/supportcases/1234/resolve will route to the resolve method of class supportcases.

REST methods have the following tagged values:

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 Image Modified	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 Image Modified	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 Image Modified	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 Image Modified	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 Image Modified	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