# REST API definition

## Response definition <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-definicjaodpowiedzi" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-definicjaodpowiedzi"></a>

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

The default ContentType used when sending requests to the service is **`application/json.`** The following is also supported **`multipart/form-data,`** if the header includes 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:

```json
{
    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. They can be accessed, for example, in this way:

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

## Exception definition

In the case of a return code other than 2XX, we will get an exception that can be handled.\
E.g. in the case of code 404 (service unavailable or incorrect 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 be handled by us, we can check whether the caught element has the fields we are interested in.

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

## Request definition <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-definicjazadania" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-definicjazadania"></a>

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 payload:

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

Below is the definition of the 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>;  // <--- an object defining timeouts for the called service, e.g. {connectionTimeout: 2000, readTimeout: 2000}
```

The PATH definition looks as follows:

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

The TIMEOUTS definition looks as follows:

```
{
    connectionTimeout: Integer,   // <--- connection establishment timeout in milliseconds
    readTimeout: Integer // <--- response read timeout in milliseconds
}
```

{% hint style="danger" %}
**No TIMEOUTS**

When the object **TIMEOUTS** is not defined for the executed REST request, the values from the configuration will be used. 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>

<br>

Parameter:

* **default** specifies the value to be used when the object **TIMEOUTS** is not defined
* **maximum** specifies the maximum value that the LOW-CODE Developer can set while preparing the request (if they set a higher one than specified, the value **maximum**)
  {% endhint %}

Example executions of requests are shown in the sections below.

## Requests <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-zadania" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-zadania"></a>

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

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

### GET <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-get" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-get"></a>

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': 'Request sent with 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 deleted successfully'};
    } else {
        return {'result': 'The item has already been deleted, or another problem occurred'};
    }
}
```

### POST <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-post" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-post"></a>

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 <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-eximeedesigner" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-eximeedesigner"></a>

API hints have been provided in Eximee Designer.

<figure><img src="/files/790c2b408556153be1d39f2c64623a1051946e13" alt=""><figcaption><p><em><strong>Figure 1</strong>. Hints for GET / POST / PUT / DELETE requests.</em></p></figcaption></figure>

<figure><img src="/files/ae2411f80bc342873396cac577d38eb1a8134715" alt=""><figcaption><p><em><strong>Figure 2</strong>. Description of the hint for a specific request (GET).</em></p></figcaption></figure>

<figure><img src="/files/a35551798483fa0bb84672d261233a97b94541f2" alt=""><figcaption><p><em><strong>Figure 3</strong>. View after inserting code automatically from the hint.</em></p></figcaption></figure>

And hints for possible serviceIds to use at the current moment.\
If there is a problem retrieving the current list of serviceIds, the editor continues to work, but does not provide information about any serviceId.

<figure><img src="/files/c38ee3159973f4242423f3885efe75f74e13495e" alt=""><figcaption><p><em><strong>Figure 4</strong>. serviceId hint outside the character: ' and "</em></p></figcaption></figure>

<figure><img src="/files/787d0470b6a2d6b786502941a70c31b757eb43d7" alt=""><figcaption><p><em><strong>Figure 5</strong>. serviceId hint limited by the character: "</em></p></figcaption></figure>

{% hint style="info" %}
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
{% endhint %}

### API Testing (Postman)

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami/definicja-api-rest.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.