Web server REST API

API — это программный интерфейс приложения. Проще говоря набор правил, которые позволяют приложениям взаимодействовать друг с другом, обеспечивая доступ к данным и функциональности через среду передачи данных.

REST расшифровывается как «передача состояния представления» (от англ. Representational State Transfer). Понятие описывает архитектурный подход к тому, как распределенные системы предоставляют интерфейс для работы с данными. Когда говорят об использовании термина «REST API» имеется в виду использование API через протокол HTTP с определенным набором ссылок (URL).

Эти ссылки представляют различные ресурсы — любая информация или контент доступный по той ссылке может быть возвращен как JSON, HTML, аудио файлы или изображения. Часто ресурсы могут иметь один или больше методов для доступа через HTTP такие, как GET, POST, PUT, DELETE.

Метод GET позволяет получить коллекцию сущностей или конкретную сущность с помощью её ID. Ссылка на получение сущностей обычно выглядит как «/api/<entityName>/», в то время как получение конкретной сущности выглядит так «/api/<entityName>/<entityID>».

Метод POST предназначен для добавления новых сущностей. Тело такого запроса должно содержать свойства нового объекта. Сервер реализующий поведение должен вернуть ID добавленной сущности. Пример ссылки: «/api/<entityName>/».

Метод PUT необходим для обновления сразу всех свойств сущности на сервере. Допустимо обновления одной сущности за раз с указанием идентификатора(ID). Пример ссылки: «/api/<entityName>/<entityID>».

Метод DELETE реализует удаление сущности на сервере. Пример ссылки: «/api/<entityName>/<entityID>». Реализация метода для удаления всех сущностей сразу не рекомендуется.

Метод PATCH предназначен для обновления произвольного числа свойств сущности с указанием их в теле запроса. Обычно реализуется обновление конкретной сущности. Пример ссылки: «/api/<entityName>/<entityID>».

Веб-сервер SimpLight, к примеру, предоставляет REST API для доступа к системе контроля и сбора данным, к таким ресурсам как: текущие каналы системы, их паспорта, история каналов, расписания, книги рецептов и т. д.

Пример GET запроса паспортов на JavaScript промисах:

  let response = fetch('/api/passports', {
    credentials: 'include'
})
.then(response => response.json())
.then(passports => {
    /*
      Получен массив объектов с паспортами
      [{
        ID: …,
        name: 'Tag name',
        ...
      }, …
      ]
    */
});

Async-await:

async function doSmth() {
let response = await fetch('/api/passports', {
    credentials: 'include'
});
let passports = await response.json();
/*
    Получен массив объектов с паспортами
    [{
      ID: …,
      name: 'Tag name',
      ...
    }, …
    ]
*/
}

В первом параметре указывается URL, ссылка, на доступ к ресурсу паспорта. Во втором объект со включением свойства необходим, поскольку на сервере используется cookie для идентификации пользователя. Использование второго метода должно быть строго в пределах функции и указанием, что она асинхронна(async).

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

let newEntity = {
    name: 'Foo',
    kind: 'Fearsome'
};
let response = fetch('/api/entitySample/', {
    credentials: 'include',
    method: 'POST',
    body: JSON.stringify(newEntity),
    headers: {
      'Content-Type': 'application/json'
    }
})
.then(response => {
    if (response.ok) {
      // все ок. Сервер вернул код 2**
    }
})

Больше информации по использованию Fetch API может быть найдено на MDN или других ресурсах.