RestApi - Integrations with external systems

Feature available from platform version: 2.2924.0

The feature is active for all customers. It does not require any activation flag.

API change

Calls via context.api() have been replaced api.rest.v1. This is the only correct way to perform requests.

The functionality to call 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 for communication between information systems that is 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 usually takes place in the 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 (nowadays used less often, mainly in test environments).

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

---

Response statuses (HTTP status codes)

The server in response to a request returns a HTTP status code, which informs about the result of the operation:

Code	Meaning
200 OK	Operation completed successfully
201 Created	A new resource was created
400 Bad Request	Bad request (e.g. invalid input data)
401 Unauthorized	No authorization or invalid token
404 Not Found	The 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 possibly the body (for POST / PUT).

2. Sending the request – communication with the external API via HTTP.

3. Receiving the response – processing the 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 – client and server can be implemented in any technologies.

• Popularity – wide support in libraries and developer tools.