Перейти к содержанию

Обзор

API (Application Programming Interface) — язык для взаимодействия приложений между собой. Описание правил такого языка называется спецификацией, а данные, которыми обмениваются приложения — сообщениями. Сообщения обычно идут парами запрос-ответ(request-response).

REST API

REST API (Representational State Transfer — передача репрезентативного состояния) также использует запросы и ответы, что мало чем отличается от посещения веб-страницы. Необходимо соответствующим образом выполнить запрос к ресурсу на сервере, и сервер ответит запрошенной информацией. Для доступа клиентских приложений к данным в REST API используются такие методы как POST, GET, PUT, PATCH и DELETE. Обмен данными осуществляется обычно по протоколу HTTP(S).

Из-за того, что приходится каждый раз заново передавать все данные для обработки запроса, объем сообщений увеличивается. Чтобы сохранить высокую скорость обмена, данные передаются в максимально сжатом формате. Чаще всего REST API использует формат JSON.

В "Симплайт 5" REST API может использоваться для интеграции с корпоративным уровнем (MES, ERP), внешними IoT-платформами, а также для разработки пользовательских приложений. С помощью HTTP-запросов можно считывать значения тегов проекта на сервере, исторические данные (моменты) и статусы оборудования, а также отправлять управляющие команды.

Методы

Как правило, для взаимодействия между клиентом и сервером достаточно пяти методов:

  • GET — получение информации об объекте (ресурсе).
  • POST — создание нового объекта (ресурса).
  • PUT — полная замена объекта (ресурса) на обновленную версию.
  • PATCH — частичное изменение объекта (ресурса).
  • DELETE — удаление информации об объекте (ресурсе).

Пример запроса

Ниже показан пример HTTP-запроса информации о статусе сервера "Симплайт 5" для REST-клиента. Предполагается, что проект развернут на машине с установленной средой разработки и используется порт по умолчанию (8080).

@host = https://127.0.0.1:8080

###
GET {{host}}/api/server/info

Аналогичный запрос можно выполнить в строке интернет-браузера:

https://127.0.0.1:8080/api/server/info

Примечание

Использовать интернет-браузер можно только для простых запросов — в данном случае, чтобы быстро протестировать работу с API. Для выполнения сложных запросов, требующих авторизации, рекомендуется использовать внешний REST-клиент.

Ответ на запрос будет следующим:

{
  "authRequired": false,
  "status": "ok"
}

Структура ответа

После выполнения запроса сервер возвращает клиентскому приложению ответ. Он включает код ответа, заголовки и тело ответа.

Заголовки в ответе определяют формат передаваемых данных, спецификацию и версию протокола обмена, и другие сведения. Тело ответа — это информация, которую запрашивал клиент. Ответ тоже чаще всего передается в формате JSON. Но тело ответа может быть и пустым.

Код ответа — это признак успешности выполнения запроса. Для унификации используются стандартные коды ответа. Они представляют собой трехзначные числа.

  1. Коды 1хх — информационные.

  2. Коды 2хх говорят об успешном выполнении запроса:

    • 200 OK – если клиентом были запрошены какие-либо данные, то они находятся в заголовке или теле сообщения.
    • 201 OK – создан новый ресурс.

  3. Коды 3xx обозначают перенаправление или необходимость уточнения:

    • 300 — на отправленный запрос есть несколько вариантов ответа. Чтобы получить нужный вариант, клиент должен уточнить запрос.
    • 301 — запрашиваемый адрес перемещен.
    • 307 — запрашиваемый адрес временно перемещен.

  4. Коды 4хх говорят о том, что при выполнении запроса возникла ошибка, и это ошибка на стороне клиента.

    • 400 – Bad Request. Запрос некорректный.
    • 401 – Unauthorized. Запрос требует аутентификации пользователя.
    • 403 – Forbidden. Доступ к сервису запрещен.
    • 404 – Not found. Ресурс не найден.

  5. Коды 5хх говорят об ошибке на стороне сервера.

    • 503 — сервис недоступен.
    • 504 — таймаут (превышено допустимое время обработки запроса).

В ответе на запрос из предыдущего раздела при использовании REST-клиента помимо запрашиваемой информации будет содержаться служебная информация и код.

GET /api/server/info
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
HTTP/1.1 200 OK  
Access-Control-Allow-Origin: * 
Content-Type: application/json; charset=utf-8 
Date: Mon, 13 Jul 2026 17:01:50 GMT
Content-Length: 35
Connection: close

{
  "authRequired": false,
  "status": "ok"
}

Расшифровка служебной информации ответа:

  1. Используется протокол HTTP/1.1. Запрос обработан успешно. В теле ответа содержится запрашиваемая информация.
  2. Разрешает кросс-доменные запросы с любого источника.
  3. Тело ответа представляет из себя JSON-документ.
  4. Момент генерации ответа сервером.
  5. Тело ответа (JSON-строка) занимает 35 байт.
  6. Сервер сообщает, что после отправки этого ответа TCP-соединение будет закрыто.
  7. Пустая строка.
  8. Ответ на запрос.

Расшифровка тела ответа:

{
  "authRequired": false,
  "status": "ok"
}
  • "authRequired": false — требуется ли аутентификация на сервере. В данном случае ответ отрицательный.
  • "status": "ok" — статус работы сервера.