ElementaryBlock Element RESTCall/en

Introduction

REST calls are HTTP-requests. A request may be a GET-, PUT-, DELETE- or POST-request, and the type of request depends on the REST service implementation on the server side.

Usually, the HTTP URL is of the form "http://<serverName>/rest/<object-locator>", where "<serverName>/rest" is the so called "end point" and fix, and "<object-locator>" addresses the particular object or sub-service to be manipulated or called. The details vary among the various REST services, and you have to consult the service's documentation.

URL Generation

In order to provide a flexible and easy to use interface, the URL for the HTTP-request is constructed by concatenating an endPoint-URL and an object-locator string. This allows for the full URL to be defined in various ways:

• static URL
• dynamic URL
• static endpoint + dynamic object-locator
• dynamic endPoint + static object-locator
• dynamic endPoint + dynamic object-locator

Static URL

For tests, where no parametrization is required and the URL is constant, specify the full URL (i.e. endPoint plus object-locator) in the REST-action's declaration page's "endPoint" field, and leave the "objectLocator" pin unconnected (or remove the pin). Also remove any "__url__" pin (or leave it unconnected).

Dynamic URL

Here, the full URL (endPoint plus object-locator) is provided by the "objectLocator" pin - either via a freeze value, another action block or an environment variable. Leave the "endPoint" field in the declaration page empty, and remove the "__url__" pin or leave it unconnected.

Static Endpoint + Dynamic object-locator

Here, the endpoint-URL is constant and defined in the declaration page, and the object-locator is provided by the pin's value. These two are concatenated. Use this, if the endPoint (server) is fix, but the object to be addressed is variable and provided by either another action or an environment variable.

Dynamic Endpoint + Static object-locator

Here, the endpoint-URL is dynamic (i.e. when the same REST-service is to be called on different hosts) but the object-locator is fix. For this, leave the endPoint field in the declaration page empty, freeze the objectLocator pin to the object-locator valeu, and provide the server endPoint via the "__url__" pin.

Dynamic EndPoint + Dynamic object-locator

Similar to the above, but also provide the object locator at the "objectLocator" pin.

Default Values

If no endPoint-URL is provided (i.e. both the field in the declaration page was left empty, and no value is provided at the "__url__" pin), expecco looks for an environment variable named "REST_URL".

URL Parameters

Some rare REST-services require additional URL-parameter in their HTTP request URL, in the form:

http://host/rest/locator&foo=fooValue&bar=barValue

For this, define the "HTTP-contentType" in the declaration page as "application/x-www-form-urlencoded" and add input pins named "foo" and "bar". Then provide the required fooValue and barValue at those pins. Of course, these can also come from another action, a freeze value or an environment variable. The pin's name determines the url-parameter name.

HTTP Username and Password

If the HTTP-request requires HTTP-authentication with username and password, these can be specified by either additional pins named "__user__" and "__password__" or via environment variables named "REST_user" and "REST_password". Those pins are not present by default and have to be added manually in the schema page.

Input Body

POST and PUT requests usually need additional input data, which is transmitted with the request. This should be provided (in the appropriate format) at the "httpBody" pin. This pin can be removed, or left unconnected, if your REST-call does not need such a body. However, if needed, it must be formatted as required by the request: usually, this will be a JSON encoded object but can also be XML-encoded or even encoded in a proprietary format. Please consult the REST service's documentation on details. In most typical situations, this body will be generated by either the JSON encoder action, or by an XML encoder. For simple bodies, it may also be generated using the String-format action and a body template.

Response Object

The REST call will return an HTTP-response, which contains the responseText. If the response is JSON encoded, the decoding can be done by the REST action itself, if the "__decode__" pin is given a "true" value. Otherwise, leave the "__decode__" pin unconnected (it defaults to "false") and pass the responseText to a decode action. If the text is XML encoded, you can use the XML-parse action block - otherwise, you may need to program your own decoder (usually as elementary action). If "__decode__" is "true", the decoded response object will be provided there. In any case will the raw (undecoded) response text be available at the "responseText" output.

HTTP Response

In addition to the above will the original HTTP-response be provided at the "httpResponse" output pin. Individual HTTP response fields can be extracted from that, if required. The responseCode and mimeType are already extracted from the response object and always provided at the corresponding output pins.

Out-of-the-Box Examples

Getting the Expecco Version

Expecco's Builtin REST Service

Expecco itself includes a REST service, which is normally used by quality management systems (such as expeccoALM) to remote-control test executions running on a test-slave machine. This service is started via the "Extras" → "WebServices" → "Expecco Remote Service (REST)" menu item. Once started, it will respond to REST requests at the endpoint URL "localhost:9090/remote" and provide various procedure- and query- calls. One such service endpoint is "/ping", which returns JSON encoded version information of the running expecco (this REST call is actually used by expeccoALM to check for slave-machine availability).

Adding a PING-request Action

First create the REST-action via the menu, and navigate to the declaration page:

Here, the "endPoint" field is left empty, so the action can be used with any service host. Then, navigate to the schema page, change the value for "__decode__" to "true" (because the expecco-REST service will deliver JSON encoded data) and freeze the "objectLocator" pin to the "remote/ping", the object-locator for the ping service entry:

Finally try it in the "Test/Demo" page, providing the localhost's endPoint ("localhost:9090") at the "__url__" input:

Then, run it and take a look at the output pins:

As you can see, the full response text (JSON encoded) is provided at the "responseText" pin, and the decoded object (an ordered dictionary) at the "responseObject" pin. The later contains a key-value pair for "expeccoVersion". To further extract individual fields, use the "Collection [ElementAt]" action, with "expeccoVersion" as key:

and find the version string at that action's output:

---

Copyright © 2014-2024 eXept Software AG