Rest API definition

Definition of response

The API supports ONLY REST services that return the type application/json .

The default ContentType with which we send requests to the service is application/json. Also supported is multipart/form-data, if the header contains the parameter {'Content-Type': 'multipart/form-data'}. For example:

api.rest.v1.get('serviceId', {queryParams: {'key': 'value'}}, {'Content-Type': 'multipart/form-data'});

The response from the service looks as follows:

{
    status: {
        code: int,
        message: String
    },
    headers: Map<String, String>,
    body: Map<String, Object>
}

All elements in the response are processed as native variables in JavaScript. You can access them, for example, in this way:

response.status.code   // <--- getting the value from the `code` field, containing the response code, e.g. 200
response.status.message   // <--- getting the value from the `message` field, containing the response message, e.g. "Accepted"
 
response.headers.language    // <---  getting the value of the return header named `language`
 
response.body.user.type    // <--- getting the value of a specific field from the response, where the response looks like: {"user": {"type": "userType"}}

Definition of exception

In the case of a return code other than 2XX, we will get an exception that can be handled. For example in a situation with code 404 (service not available or wrong address), code 405 (invalid method) or code 500 (internal service error).

The exception looks as follows:

{
    status: {
        code: int,
        message: String
    },
    body: String
}

To verify whether this is an exception to handle by us, we can check whether the caught element has the fields that interest us.

try {
    // call the external service
} catch (exception) {
    if (exception.status !== undefined && exception.status.code !== undefined) {
        // handling our exception, e.g. returning a default value
    } else {
        // this is not our exception, we can handle it or rethrow it
        throw exception;
    }
}

Definition of request

A request can be parameterized.

Requests can contain a payload:

api.rest.v1.post(SERVICE_ID, PATH, HEADER, PAYLOAD, TIMEOUTS);
api.rest.v1.put(SERVICE_ID, PATH, HEADER, PAYLOAD, TIMEOUTS);

And they can be without a payload:

api.rest.v1.get(SERVICE_ID, PATH, HEADER, TIMEOUTS);
api.rest.v1.delete(SERVICE_ID, PATH, HEADER, TIMEOUTS);

Below is the definition of parameters:

SERVICE_ID: String;  // <--- e.g. 'myServiceId'
 
HEADER: Map<String, String>;  // <--- e.g. {'myHeader': 'value'}
 
PAYLOAD: Map<String, Object>;  // <--- any valid object, e.g. {'user': 123, 'name': 'Lisa'}
TIMEOUTS: Map<String, Integer>;  // <--- object defining timeouts for the called service e.g. {connectionTimeout: 2000, readTimeout: 2000}

The PATH definition looks as follows:

{
    pathParams: List<String>,   // <--- successive elements of the address to the service, e.g. ['api', 'v1', 'path', 'to', 'endpoint'] for /api/v1/path/to/endpoint
    queryParams: Map<String, String> // <--- keep in mind that query params are always strings
}

The TIMEOUTS definition looks as follows:

{
    connectionTimeout: Integer,   // <--- time limit for establishing a connection in milliseconds
    readTimeout: Integer // <--- time limit for reading the response in milliseconds
}

No TIMEOUTS

If the object TIMEOUTS is not defined for the executed REST request, values taken from the configuration will be assigned. They are located in the parameters:

<config>

<eximee> <restclient> <connection-timeout> <default>1000</default> <maximum>10000</maximum> </connection-timeout> <read-timeout> <default>10000</default> <maximum>30000</maximum> </read-timeout> </restclient> </eximee>

</config>

The parameter:

  • default specifies the value taken when the object TIMEOUTS is not defined

  • maximum specifies the maximum value that a LOW-CODE Developer can set when preparing a request (if a larger one is set than given, the value will be set to maximum)

Example request executions are in the sections below.

Requests

For each of the requests below we assume a consistent configuration:

scriptservice:
  api:
    - serviceId: "serviceId"
      url: "http://my.service/"

GET

Request without payload.

Examples:

// curl -X GET http://my.service/
api.rest.v1.get('serviceId', {}, {});
 
// curl -X GET http://my.service/get/path
api.rest.v1.get('serviceId', {pathParams: ['get', 'path']}, {});
 
// curl -X GET http://my.service/get?key=value
api.rest.v1.get('serviceId', {pathParams: ['get'], queryParams: {'key': 'value'}}, {});
 
// curl -X GET http://my.service/get?key=value -H 'Header-Key: header-value'
api.rest.v1.get('serviceId', {pathParams: ['get'], queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'});
 
// curl -X GET http://my.service/?key=value -H 'Header-Key: header-value'
api.rest.v1.get('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'});
 
// curl -X GET http://my.service/?key=value -H 'Header-Key: header-value' connectionTimeout: 2s readTimeout: 5s
api.rest.v1.get('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {connectionTimeout: 2000, readTimeout: 5000});

And an example ScriptService:

function callService(context) {
    const response = api.rest.v1.get('httpbin', {pathParams: ['get']}, {});
    const requestSize = response.headers['Content-Length'];
    return {'result': 'Sent a request of size: ' + requestSize};
}

DELETE

Request without payload.

Examples:

// curl -X DELETE http://my.service/
api.rest.v1.delete('serviceId', {}, {});
 
// curl -X DELETE http://my.service/delete/path
api.rest.v1.delete('serviceId', {pathParams: ['delete', 'path']}, {});
 
// curl -X DELETE http://my.service/delete?key=value
api.rest.v1.delete('serviceId', {pathParams: ['delete'], queryParams: {'key': 'value'}}, {});
 
// curl -X DELETE http://my.service/delete?key=value -H 'Header-Key: header-value'
api.rest.v1.delete('serviceId', {pathParams: ['delete'], queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'});
 
// curl -X DELETE http://my.service/?key=value -H 'Header-Key: header-value'
api.rest.v1.delete('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'});
 
// curl -X DELETE http://my.service/?key=value -H 'Header-Key: header-value' connectionTimeout: 2s readTimeout: 5s
api.rest.v1.delete('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {connectionTimeout: 2000, readTimeout: 5000});

And an example ScriptService:

function callService(context) {
    const response = api.rest.v1.delete('httpbin', {pathParams: ['delete']}, {});
 
    if (response.status.code === 200) {
        return {'result': 'Item successfully deleted'};
    } else {
        return {'result': 'The item has already been deleted, or another problem occurred'};
    }
}

POST

Request with payload.

Examples:

// curl -X POST http://my.service/ -d '{}'
api.rest.v1.post('serviceId', {}, {}, {});
 
// curl -X POST http://my.service/post/path -d '{}'
api.rest.v1.post('serviceId', {pathParams: ['post', 'path']}, {}, {});
 
// curl -X POST http://my.service/post -d "{'user': 123, 'name': 'Lisa'}"
api.rest.v1.post('serviceId', {pathParams: ['post']}, {}, {'user': 123, 'name': 'Lisa'});
 
// curl -X POST http://my.service/post?key=value -d '{}'
api.rest.v1.post('serviceId', {pathParams: ['post'], queryParams: {'key': 'value'}}, {}, {});
 
// curl -X POST http://my.service/post?key=value -d '{}' -H 'Header-Key: header-value'
api.rest.v1.post('serviceId', {pathParams: ['post'], queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {});
 
// curl -X POST http://my.service/post?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value'
api.rest.v1.post('serviceId', {pathParams: ['post'], queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'});
 
// curl -X POST http://my.service/?key=value -d '{}' -H 'Header-Key: header-value'
api.rest.v1.post('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {});
 
// curl -X POST http://my.service/?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value'
api.rest.v1.post('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'});
 
// curl -X POST http://my.service/?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value' connectionTimeout: 2s readTimeout: 5s
api.rest.v1.post('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'}, {connectionTimeout: 2000, readTimeout: 5000});

// curl -X POST 'http://my.service/post/multipartFormData' --form 'given_names="Lisa"' --form 'surname="Nowak"'
api.rest.v1.post('serviceId',{pathParams:['post','multipartFormData']},{'Content-Type': 'multipart/form-data'},{given_names:'Lisa',surname:'Nowak'})

And an example ScriptService:

function callService(context) {
    const response = api.rest.v1.post('httpbin', {pathParams: ['post']}, {}, {'user': {'name': 'Bernard'}, 'type': 'changeName'});
    const newName = response.body.json.user.name;
    return {'result': 'The new name is: ' + newName};
}

PUT

Request with payload.

Examples:

// curl -X PUT http://my.service/ -d '{}'
api.rest.v1.put('serviceId', {}, {}, {});
 
// curl -X PUT http://my.service/put/path -d '{}'
api.rest.v1.put('serviceId', {pathParams: ['put', 'path']}, {}, {});
 
// curl -X PUT http://my.service/put -d "{'user': 123, 'name': 'Lisa'}"
api.rest.v1.put('serviceId', {pathParams: ['put']}, {}, {'user': 123, 'name': 'Lisa'});
 
// curl -X PUT http://my.service/put?key=value -d '{}'
api.rest.v1.put('serviceId', {pathParams: ['put'], queryParams: {'key': 'value'}}, {}, {});
 
// curl -X PUT http://my.service/put?key=value -d '{}' -H 'Header-Key: header-value'
api.rest.v1.put('serviceId', {pathParams: ['put'], queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {});
 
// curl -X PUT http://my.service/put?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value'
api.rest.v1.put('serviceId', {pathParams: ['put'], queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'});
 
// curl -X PUT http://my.service/?key=value -d '{}' -H 'Header-Key: header-value'
api.rest.v1.put('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {});
 
// curl -X PUT http://my.service/?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value'
api.rest.v1.put('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'});
 
// curl -X PUT http://my.service/?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value' connectionTimeout: 2s readTimeout: 5s
api.rest.v1.put('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'}, {connectionTimeout: 2000, readTimeout: 5000});

And an example ScriptService:

function callService(context) {
    const response = api.rest.v1.put('httpbin', {pathParams: ['put']}, {}, {'name': 'Lisa', 'country': 'PL', 'birthday': '29-02-1999'});
    const userName = response.body.json.name;
    return {'result': 'The user has been added to the database. User name: ' + userName};
}

PATCH

Request with payload.

Examples:

// curl -X PATCH http://my.service/ -d '{}'
api.rest.v1.patch('serviceId', {}, {}, {});
 
// curl -X PATCH http://my.service/post/path -d '{}'
api.rest.v1.patch('serviceId', {pathParams: ['post', 'path']}, {}, {});
 
// curl -X PATCH http://my.service/post -d "{'user': 123, 'name': 'Lisa'}"
api.rest.v1.post('serviceId', {pathParams: ['patch']}, {}, {'user': 123, 'name': 'Lisa'});
 
// curl -X PATCH http://my.service/post?key=value -d '{}'
api.rest.v1.patch('serviceId', {pathParams: ['patch'], queryParams: {'key': 'value'}}, {}, {});
 
// curl -X PATCH http://my.service/post?key=value -d '{}' -H 'Header-Key: header-value'
api.rest.v1.patch('serviceId', {pathParams: ['patch'], queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {});
 
// curl -X PATCH http://my.service/post?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value'
api.rest.v1.patch('serviceId', {pathParams: ['patch'], queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'});
 
// curl -X PATCH http://my.service/?key=value -d '{}' -H 'Header-Key: header-value'
api.rest.v1.patch('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {});
 
// curl -X PATCH http://my.service/?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value'
api.rest.v1.patch('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'});
 
// curl -X PATCH http://my.service/?key=value -d "{'user': 123, 'name': 'Lisa'}" -H 'Header-Key: header-value'  connectionTimeout: 2s readTimeout: 5s
api.rest.v1.patch('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'}, {'user': 123, 'name': 'Lisa'}, {connectionTimeout: 2000, readTimeout: 5000});

And an example ScriptService:


function callService(context) {
    const response = api.rest.v1.patch('httpbin', {pathParams: ['patch']}, {}, {'user': {'name': 'Bernard'}, 'type': 'changeName'});
    const newName = response.body.json.user.name;
    return {'result': 'The new name is: ' + newName};
}

Eximee Designer

API hints have been provided in Eximee Designer.

Figure 1. Hints for GET / POST/ PUT / DELETE requests.
Illustration 2. Description of the hint regarding a specific request (GET).

Illustration 3. View after inserting code automatically from the hint.

And hints of possible serviceId values to use at the current moment. In case of a problem retrieving the current list of serviceId, the editor continues to work but does not provide information about any serviceId.

Illustration 4. serviceId hint outside the character: ' and "

Illustration 5. serviceId hint limited by the character: "

Examples

"demo_api_RestTest" - executing requests with different parameters

"demo_api_exchangeRate_404" - exception handling

"demo_api_exchangeRate_validator" - example of a validator calling an external service

API Testing (Postman)

Postman is a tool for testing and working with APIs that allows you to easily send HTTP requests (e.g. GET, POST) and analyze server responses. (https://www.postman.com/)

PreviousRestApi configurationNextPlatform header with tenant identifier

Last updated

Was this helpful?