RestApi - Integrations with external systems

Functionality available from platform version: 2.2924.0

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

API change

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

The functionality for 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 that is based on the standard protocol HTTP. It enables data exchange between the client (e.g. an application) and the 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:

The 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 most often takes place in the format of 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, HTTPS should always be used HTTPS, to ensure communication encryption.

---

Response statuses (HTTP status codes)

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

Code	Meaning
200 OK	Operation completed successfully
201 Created	New resource created
400 Bad Request	Bad request (e.g. invalid input data)
401 Unauthorized	Missing 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 optional 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 – broad support in libraries and development tools.