8. oData

Архитектура

OData - это протокол для создания и использования RESTful API.
Таким образом, как и в случае с REST, OData основывается на HTTP, AtomPub и JSON, используя URI для адресации ресурсов канала передачи данных и доступа к ним.

Идентификация ресурсов

OData использует URI для идентификации ресурсов.

Для каждой службы OData, корень которой сокращенно обозначается как http://host/service/, можно найти следующие фиксированные ресурсы:

  1. Служебный документ
    В сервисном документе перечислены наборы сущностей, функции и отдельные элементы, которые могут быть извлечены. Клиенты могут использовать сервисный документ для навигации по модели на основе гипермедиа. Сервисный документ доступен в корневом каталоге doc/service-root: http://host/service/.
  2. Документ с метаданными
    Документ с метаданными описывает типы, наборы, функции и действия, понятные службе OData. Клиенты могут использовать документ с метаданными, чтобы понять, как запрашивать объекты в службе и взаимодействовать с ними (1). Документ с метаданными доступен по адресу http://host/service/$metadata.

Управление данными

В OData используются HTTP-методы для указания операций с ресурсами.

  1. GET: Получение данных (коллекции объектов, отдельного объекта, структурного свойства, свойства навигации, потока и т.д.).
  2. POST: Создание новых данных.
  3. PUT: Обновить существующие данные, полностью перезаписав новым объектом.
  4. PATCH: Обновить существующие данные, заменив только часть полей.
  5. DELETE: Удалить запись.

Полезные ссылки для ознакомления:

  1. Explaining OData от SAP
  2. Официальная документация по протоколу oData

oData V2 и V4

Ui5 нативно поддерживает обе версии oData.

Для SAP onPremise -- V2 (потому что бэкенд ничего другого не поддерживает)

Для CAP и других клаудных решений -- V4.

Аннотации для каждой из версий oData -- разные. Поэтому важно понимать какая версия сейчас используется. Когда читаете документацию -- смотрите раздел именно для вашей версии.

Про технические внутренние отличия двух версий протокола лучше почитать здесь: https://1dsag.github.io/UI5-Best-Practice/odata/v2vsv4.html

Правила именования сущностей и полей в oData

OData сущность Правило Хороший пример Плохой пример
Основное Используйте UpperCamelСase SalesDocument SALESDOCUMENT
Основное Без подчеркивания PurchaseOrder Purchase_Order
Основное На английском Order Zakaz
Основное Без технических названий SAP CompanyCode BUKRS
Имена сущностей Только существительные CostCenter CostCenterF4
Имена сущностей Только в единственном числе PurchaseOrder PurchaseOrderList
Имена сущностей Без названия операции SalesOrder CreateSalesOrder
Сеты Во множественном числе, либо с постфиксом Set PurchaseOrders, PurchaseOrderSet PurchaseOrder
Навигации То же самое, что и название сущности, если связь 1-1 /OrderHead('1')/OrderItem('1') /OrderHead('1')/Header_Item('1')
Навигации То же самое, что и название сета, если связь 1-M /OrderHead('1')/OrderItems /OrderHead('1')/Header_Item
Функции (V2) / Actions (V4) Используйте понятные названия BlockSalesOrder Block