> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami/definicja-api-rest.md).

# 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 with which we send requests to the service is **`application/json.`** Also supported is **`multipart/form-data,`** if the header contains 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 e.g. like this:

```
response.status.code   // <--- obtain the value from the `code` field, containing the response code, e.g. 200
response.status.message   // <--- obtain the value from the `message` field, containing the response message, e.g. "Accepted"
 
response.headers.language    // <--- obtain the value of the return header named `language`
 
response.body.user.type    // <--- obtain 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 get an exception that can be handled.\
E.g. in the case of code 404 (service not available 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 we can handle, we can check whether the caught element has the fields that interest us.

```javascript
try {
    // call an 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 payload:

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

And they can also 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 the parameters:

```
SERVICE_ID: String;  // <--- e.g. 'mojServiceId'
 
HEADER: Map<String, String>;  // <--- e.g. {'mojHeader': '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 elements of the path to the service, 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, 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>

<br>

Parameter:

* **default** specifies the value 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 a higher value is set than the one specified, the value will be set **maximum**)
  {% endhint %}

Examples of request execution are 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://moj.service/"
```

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

Request without payload.

Examples:

```
// curl -X GET http://moj.service/
api.rest.v1.get('serviceId', {}, {});
 
// curl -X GET http://moj.service/get/path
api.rest.v1.get('serviceId', {pathParams: ['get', 'path']}, {});
 
// curl -X GET http://moj.service/get?key=value
api.rest.v1.get('serviceId', {pathParams: ['get'], queryParams: {'key': 'value'}}, {});
 
// curl -X GET http://moj.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://moj.service/?key=value -H 'Header-Key: header-value'
api.rest.v1.get('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'});
 
// curl -X GET http://moj.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://moj.service/
api.rest.v1.delete('serviceId', {}, {});
 
// curl -X DELETE http://moj.service/delete/path
api.rest.v1.delete('serviceId', {pathParams: ['delete', 'path']}, {});
 
// curl -X DELETE http://moj.service/delete?key=value
api.rest.v1.delete('serviceId', {pathParams: ['delete'], queryParams: {'key': 'value'}}, {});
 
// curl -X DELETE http://moj.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://moj.service/?key=value -H 'Header-Key: header-value'
api.rest.v1.delete('serviceId', {queryParams: {'key': 'value'}}, {'Header-Key': 'header-value'});
 
// curl -X DELETE http://moj.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': 'The item was 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://moj.service/ -d '{}'

api.rest.v1.post('serviceId', {}, {}, {});
 
// curl -X POST http://moj.service/post/path -d '{}'

api.rest.v1.post('serviceId', {pathParams: ['post', 'path']}, {}, {});
 
// curl -X POST http://moj.service/post -d "{'user': 123, 'name': 'Lisa'}"
api.rest.v1.post('serviceId', {pathParams: ['post']}, {}, {'user': 123, 'name': 'Lisa'});
 
// curl -X POST http://moj.service/post?key=value -d '{}'

api.rest.v1.post('serviceId', {pathParams: ['post'], queryParams: {'key': 'value'}}, {}, {});
 
// curl -X POST http://moj.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://moj.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://moj.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://moj.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://moj.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://moj.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://moj.service/ -d '{}'

api.rest.v1.put('serviceId', {}, {}, {});
 
// curl -X PUT http://moj.service/put/path -d '{}'

api.rest.v1.put('serviceId', {pathParams: ['put', 'path']}, {}, {});
 
// curl -X PUT http://moj.service/put -d "{'user': 123, 'name': 'Lisa'}"
api.rest.v1.put('serviceId', {pathParams: ['put']}, {}, {'user': 123, 'name': 'Lisa'});
 
// curl -X PUT http://moj.service/put?key=value -d '{}'

api.rest.v1.put('serviceId', {pathParams: ['put'], queryParams: {'key': 'value'}}, {}, {});
 
// curl -X PUT http://moj.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://moj.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://moj.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://moj.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://moj.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://moj.service/ -d '{}'

api.rest.v1.patch('serviceId', {}, {}, {});
 
// curl -X PATCH http://moj.service/post/path -d '{}'

api.rest.v1.patch('serviceId', {pathParams: ['post', 'path']}, {}, {});
 
// curl -X PATCH http://moj.service/post -d "{'user': 123, 'name': 'Lisa'}"
api.rest.v1.post('serviceId', {pathParams: ['patch']}, {}, {'user': 123, 'name': 'Lisa'});
 
// curl -X PATCH http://moj.service/post?key=value -d '{}'

api.rest.v1.patch('serviceId', {pathParams: ['patch'], queryParams: {'key': 'value'}}, {}, {});
 
// curl -X PATCH http://moj.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://moj.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://moj.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://moj.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://moj.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>. GET / POST / PUT / DELETE request hints.</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 automatically inserting code from the hint.</em></p></figcaption></figure>

And hints for possible serviceIds that can be used at the current moment.\
If there is a problem fetching 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**" - performing requests with different parameters

"**demo\_api\_exchangeRate\_404**" - exception handling

"**demo\_api\_exchangeRate\_validator**" - example of a validator with a call to 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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