Rest API от чайника для чайников

06.06.22

Интеграция - WEB-интеграция

На написание статьи побудило чтение книги "Технологии интеграции "1С:Предприятия 8.3"" Хрусталевой Е.Ю. В первой главе там постоянно чередуются слова REST, REST-интерфейс, архитектура REST и т.д. Мне стало интересно, я начал копать, что это такое, и тема оказалась достаточно интересной.

Начнём с некоторых определений

Перед тем, как дать определение REST API, нужно ввести несколько общих определений.

Архитектурный стиль – это набор согласованных ограничений и принципов проектирования, позволяющий добиться определённых свойств системы

API (Application programming interface) - программный интерфейс приложения для взаимодействия с другими приложениями.

Вот теперь можно давать определение REST API.

REST API (Representational State Transfer, передача состояния представления) - архитектурный стиль разработки API веб-приложений или компонентов распределённого приложения, используя протокол HTTP.

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

 
Краткая историческая справка

Целевые свойства REST API

  • Производительность
  • Масштабируемость, выраженная в:
    • простота **унифицированного** интерфейса
    • лёгкость внесения изменений, т.е. способность эволюционировать, приспосабливаясь к новым требованиям
    • надёжность / отказоустойчивость
    • переносимость компонентов

Получается, что REST API потребовался, так как возникла потребность создавать производительные, надежные и легко поддающиеся изменению обмены между клиентом и сервером. За счёт чего же это достигается?

Принципы построения REST API

Существует 6 **принципов**, которым должен соответствовать REST-интерфейс:

  1. единый интерфейс - ресурсы должны быть однозначно идентифицированы посредством одного URL-адреса
  • н-р: неверно чтобы для одно и того же объекта для разных HTTP-запросов были разные интерфейсы
GET ...\getusers
PUT ...\createusers
  •  верно - когда интерфейс один, а что делать определяется видом запроса
GET ...\users
PUT ...\users
  1. Всегда использовать клиент-серверное взаимодействие и разграничивать данные между ними
  • пользовательский интерфейс и вопросы сбора запросов — на стороне клиента.
  • доступ к данным, управление рабочей нагрузкой и безопасность — на стороне сервера.
  1. Использовать Stateless protocol (протокол без сохранения состояния) - в период, между запросами никакая информация о *состоянии* клиента на сервере не хранится
  •  Следствие: в запросе сервер должен получать всю необходимую информацию для выполнения этого запроса
  1. Использовать кэширование - все ресурсы должны разрешать кэширование, если явно не указано, что оно невозможно, следовательно, все ответы сервера должны иметь явные или неявные обозначения кэшируемых и не кэшируемых ответов
  2. Учитывать слои взаимодействия - система может быть многоуровневой, и как следствие клиент не может однозначно знать взаимодействует он напрямую с сервером или с промежуточным узлом
  3. Код по требованию (необязательное условие) - REST может позволить расширить функциональность клиента за счёт загрузки кода с сервера (апплеты или скрипты)

REST и RESTful - в чём разница?

Термин RESTful был введён, чтобы различать сервисы, построенные чётко по шести указанным выше требованиям, от тех, которые соблюдают только часть  требований.

RESTful - это приложение, в котором соблюдаются все требования к построению архитектуры REST API. По поводу этого см. чуть ниже в раздел "Недостатки и критика REST API"

Стандарты REST API

Надо понимать, что REST - это не протокол, поэтому у него нет чёткого и единственного стандарта разработки. Единственное, что чётко прописано - транспортом REST-запросов является HTTP. Всё остальное (формат данных, интерфейса API и т.д.) - на усмотрение разработчика.

Недостатки и критика REST API

  • завязка на HTTP, спецификация которого имеет свои ограничение
    • иногда это приводит к тому, что приходит эмитировать поведение некоторых специфических методов
  • ограничения выборки, наложенные создателем интерфейса API
    • чрезмерная выборка - н-р: есть сервис, которые возвращает контактные данные пользователя. Нам надо получить только имя, но сервис настроен на возврат имени, телефона и т.д.
    • недостаточная выборка - например сервис, упомянутый выше, возвращает только телефон по умолчанию, а нам нужны все доступные телефоны
  • Отсутствие однозначного понимания, что такое RESTful. А без этой ясности сложно сравнить сервисы и дать однозначный ответ - правильно ли спроектирован сервис или нет.
    • Достаточно ли использовать код HTTP-ответа 200 при создании записи или надо использовать 201?
    • Достаточно ли использовать код HTTP-ответа 200 при обновлении записи или надо использовать 250?

REST API в 1С

Долго на этом останавливаться не буду, просто обзорно распишу. В 1С можно выделить следующие способы работы с REST:

  • создавать свой REST API (метаданные "Общие - HTTP-сервис")
  • обратиться к любому REST API (методы встроенного языка: HTTPСоединение, HTTPзапрос, HTTPОтвет)
  • взаимодействовать с автоматически генерируемый REST-интерфейсом платформы (см. Автоматический REST-интерфейс через протокол OData)

Выводы

В данной статье я постарался дать определение и описание того, что такое REST API. Недаром говорят, что если хочешь до конца понять термин или технологию - постарайся рассказать о ней другому человеку, что в данной статье и проделано ^_^.

Напоследок отмечу, что главный плюс REST - это простота, именно поэтому он долгое время являлся самым популярным стандартом для организации взаимодействия клиента и сервера. Является ли он таким на данный момент, ответить сложно, ибо есть множество интересных альтернатив: старенький, но надёжный, SOAP, передовой GraphQL, RPC, JSON-pure API и многое другое.

REST API WEB

См. также

Интеграция Альфа Авто 5 / Альфа Авто 6 и AUTOCRM / Инфотек

Сайты и интернет-магазины WEB-интеграция Платформа 1С v8.3 Конфигурации 1cv8 1С:Управление торговлей 11 Автомобили, автосервисы Россия Управленческий учет Платные (руб)

Интеграционный модуль обмена между конфигурацией Альфа Авто 5 и Альфа Авто 6 и порталом AUTOCRM. Данный модуль универсален. Позволяет работать с несколькими обменами AUTOCRM разных брендов в одной информационной базе в ручном и автоматическом режиме.

36000 руб.

03.08.2020    15750    10    17    

11

Интеграция 1С — Битрикс24. Обмен задачами

Сайты и интернет-магазины Интеграция WEB-интеграция Платформа 1С v8.3 Конфигурации 1cv8 Управленческий учет Платные (руб)

Интеграция 1С и Битрикс24. Разработка имеет двухстороннюю синхронизацию 1С и Битрикс24 задачами. Решение позволяет создавать пользователя в 1С из Битрикс24 и наоборот. Данная разработка технически подходит под все основные конфигурации линейки продуктов 1С:Предприятие 8.3 (8.3.18.1289). При приобретении предоставляется 1 месяц бесплатных обновлений разработки. Доступна демо-версия продукта с подключением Вашего Битрикс24

5040 руб.

04.05.2021    17558    6    15    

13

Интеграция с сервисом vetmanager

WEB-интеграция Платформа 1С v8.3 Бухгалтерский учет 1С:Бухгалтерия 3.0 Бытовые услуги, сервис Платные (руб)

Внешняя обработка разрабатывалась для загрузки документов из Ветменеджер в 1С: Бухгалтерия 3.0

12000 руб.

02.02.2021    16364    42    49    

23

[Расширение] БОР-Навигатор.Культура

Зарплата Бюджетный учет WEB-интеграция Обмен с ГосИС Платформа 1С v8.3 Сложные периодические расчеты 1С:Зарплата и кадры государственного учреждения 3 Государственные, бюджетные структуры Россия Бюджетный учет Платные (руб)

Расширение конфигурации, включающее в себя объекты, необходимые для подготовки и сдачи отчета "Штатная численность" системы "БОР-Навигатор.Культура" в программе "1С:Зарплата и кадры государственного учреждения", редакция 3.1.

8400 руб.

01.02.2019    25746    9    0    

7

Заполнение по ИНН или наименованию реквизитов контрагента по данным сайта ФНС

Обмен с ГосИС WEB-интеграция Платформа 1С v8.3 Управляемые формы 1С:Комплексная автоматизация 1.х 1С:Бухгалтерия 2.0 1С:Управление торговлей 10 1С:Управление производственным предприятием 1С:Управление нашей фирмой 1.6 1С:Бухгалтерия государственного учреждения 1С:Документооборот 1С:ERP Управление предприятием 2 1С:Бухгалтерия 3.0 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х Платные (руб)

Обработка является альтернативой механизму, разработанному фирмой 1С и заполняющему реквизиты контрагента по ИНН или наименованию. Не требуется действующей подписки ИТС. Вызывается как внешняя дополнительная обработка, т.е. используется, непосредственно, из карточки контрагента. Заполнение по ИНН или наименованию реквизитов контрагента по данным сайта ФНС (egrul.nalog.ru) для БП 2.0, БП 3.0, БГУ 1.0, БГУ 2.0, УТ 10.3, УТ 11.x, КА 1.1, КА 2.x, УПП 1.x, ERP 2.x, УНФ 1.5, УНФ 1.6, УНФ 3.0, ДО 2.1

2400 руб.

28.04.2016    88589    160    215    

318
Комментарии
В избранное Подписаться на ответы Сортировка: Древо развёрнутое
Свернуть все
1. DrAku1a 1679 09.07.22 11:11 Сейчас в теме
Вопрос от "чайника":
Фреймворки в целом рекомендуют использовать запросы видаА если использовать что-то видаэто нарушает принципы RESTfull API ?
2. zeltyr 567 11.07.22 17:34 Сейчас в теме
(1) Честно, у меня нет однозначного ответа на этот вопрос, могу изложить только свои скромные измышления.

Параметры обычно используются для сортировки и фильтрации данных (н-р: ?page=1&sort=title), или для ограничения области действия операции (н-р: ?action=delete&id=5). А для получения карточки по id лучше использовать вариант 1, как описывают стандарты фреймоворков, иначе могут появиться вопросы - а что делает этот сервис? может он выполняет какой-то специфический параметризуемый запрос, а не просто получение данных пользователя.

П.С. Указание на то, что лучше использовать синтаксис вида http://hostname/api/users/{id}/, есть ещё в различных соглашениях, н-р: Соглашения по Rest API (IBM)
Оставьте свое сообщение