> 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 the type **`application/json`** .

The default ContentType used when sending requests to the service is **`application/json.`** Also supported is **`multipart/form-data,`** if the parameter is passed in the header **`{'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 JavaScript variables. They can be accessed, for example, like this:

```
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 any return code other than 2XX, we get an exception that can be handled.\
E.g. in the case of code 404 (service unavailable or invalid 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 that we should handle, we can check whether the caught item 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 let it pass through
        throw exception;
    }
}
```

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

A request can be parameterized.

Requests may 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 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 the timeouts for the called service, e.g. {connectionTimeout: 2000, readTimeout: 2000}
```

The PATH definition looks as follows:

```
{
    pathParams: List<String>,   // <--- subsequent elements 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 taken from the configuration will be assigned. They are found 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 they set a higher value than the one given, the value will be set **maximum**)
  {% endhint %}

Example request executions are in the sections below.

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

For each of the following requests, 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': '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': '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://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': '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 was 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': '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 the 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 automatically inserting code from the hint.</em></p></figcaption></figure>

And hints for possible serviceId values to use at the current moment.\
If there is a problem fetching the current list of serviceId values, 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 characters: ' 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**" - an example 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
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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.