# RestApi - Integrations with external systems

{% hint style="warning" %}
Functionality available from platform version: 2.2924.0

The functionality is active for all clients. It does not require any activation flag.
{% endhint %}

{% hint style="warning" %}
API change

Calling via context.api() has been replaced **api.rest.v1**. This is the only correct way to make requests.
{% endhint %}

{% hint style="info" %}
The functionality of calling external REST services is available for scripts (scriptService), script tasks (scriptTask), and script validators (validationScript).
{% endhint %}

## Integration with external services via REST API

### What is REST?

**REST (Representational State Transfer)** is an architectural style of communication between IT systems, based on the standard protocol **HTTP**.\
It enables data exchange between a client (e.g. an application) and a server (e.g. an external service) in a **lightweight, simple, and scalable**.

Each resource (e.g. user, order, document) is identified by a unique **URL**, and operations on it are performed using standard HTTP methods:

| Method          | Description                    |
| --------------- | ------------------------------ |
| `GET`           | Retrieves data from the server |
| `POST`          | Creates a new resource         |
| `PUT` / `PATCH` | Updates an existing resource   |
| `DELETE`        | Deletes a resource             |

***

### Data format

Information exchange in REST API is most often done in the format **JSON** (less often XML).\
JSON is human-readable, easy to process, and natively supported by most programming languages.

***

### Authorization and security

Access to external services usually requires **authorization**, which ensures that only authorized applications or users can use the API.

The most common mechanisms are:

* **API Key** – a simple identification key added to the header or request parameter;
* **Bearer Token (OAuth 2.0)** – a modern standard based on access tokens;
* **Basic Auth** – login and password encoded in the header (currently used less often, mainly in test environments).

> 🔒 When integrating with external services, you should always use **HTTPS**, to ensure communication encryption.

***

### Response statuses (HTTP status codes)

In response to a request, the server returns a **HTTP status code**, which indicates the result of the operation:

| Code                        | Meaning                               |
| --------------------------- | ------------------------------------- |
| `200 OK`                    | Operation completed successfully      |
| `201 Created`               | A new resource has been created       |
| `400 Bad Request`           | Bad request (e.g. invalid input data) |
| `401 Unauthorized`          | No authorization or invalid token     |
| `404 Not Found`             | Resource does not exist               |
| `500 Internal Server Error` | Server-side error                     |

***

## Typical REST integration flow

1. **Building the request** – preparing the URL, headers (e.g. authorization, data type) and an optional body (for `POST` / `PUT`).
2. **Sending the request** – communication with an external API via HTTP.
3. **Receiving the response** – processing data returned in JSON format.
4. **Error handling** – interpreting status codes and error messages.
5. **Data mapping** – saving or using the received data in the local system.

***

## Advantages of REST

* **Simplicity** – easy to understand and implement.
* **Scalability** – works well in distributed environments.
* **Independence** – the client and server can be implemented in any technologies.
* **Popularity** – broad support in libraries and development tools.


---

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