RestApi - Integrations with external systems

Functionality available from platform version: 2.2924.0

The functionality is active for all clients. It does not require any activation flag.

API change

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

The functionality of calling external REST services is available for scripts (scriptService), script tasks (scriptTask), and script validators (validationScript).

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.