EM

RACS (REST API CRUD Service) v3

Новое в версии

  • Сервис работает с объектами данных. Поля хранимого в БД документа могут иметь любой тип из поддерживаемых C# MongoDB.Driver: список.
  • Поиск/изменение документов возможен с учетом (почти) всего функционала работы с объектами, предоставляемого C# MongoDB.Driver.
  • Предопределенные/служебные поля для удобства чтения начинаются с символа подчеркивания.
  • Существует возможность кеширования предоставляемых сервисом данных.

API:

операция CRUDметод запроса HTTPURLОписание
CREATEPOST/v3Добавление элементов
READGET/v3/{id}Получение элемента по его id
READGET/v3Поиск элементов по фильтру
READPOST/v3/getПолучение элементов по фильтру (аналогичен GET запросу /v3 с телом)
UPDATEPATCH/v3/{id}Модификация элемента по его id
UPDATEPATCH/v3Модификация элементов по фильтру
DELETEDELETE/v3/{id}Удаление элемента по его id
DELETEDELETE/v3Удаление элементов по фильтру
—BATCH/v3Пакетный режим (одновременное выполнение нескольких команд одним запросом)
—GET/v3/clear-cacheОчистка кэша

/v3

Все запросы всегда возвращают код 200 и объект JSON.

Параметры запросов:

Параметры url запроса:

  • resource (required) — ресурс. Ресурсом может быть сайт или проект, контрагент, это верхний уровень структуры данных. Если не передаётся явно, берётся из referer-параметра (hostname ограничивается именем домена второго уровня) запроса. Параметр служит для внутренней идентификации и в БД не сохраняется.
  • dataset — идентифицирует набор сущностей для разделения доступа. Если не передаётся явно, берётся из referer-параметра (путь текущей страницы) запроса. Параметр служит для внутренней идентификации и в БД не сохраняется.
  • body — содержимое тело запроса так же может быть передано через url в виде Url-encoded JSON объекта в этом параметре. При указании параметра тело запроса игнорируется.
  • cacheTag — тег кэша (см. Управление кэшем).

Поле resource заполняется из заголовка запроса Referer и может быть переопределен в url запроса.

Объект данных передается в теле запроса (должен присутствовать заголовок «Content-Type»: «application/json»).

Служебные поля документов:

  • _id — уникальный идентификатор документа, по нему происходит поиск в /v3/{id}.
  • _created — timestamp создания документа.
  • _modified — timestamp последней модификации документа.
  • _ip — ip адрес, с которого производилась последняя модификация документа.
Добавление документа в БД.

POST запрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com с телом { "Name" : "Tom", "Age" : 38, "Company" : { "Title" : "Microsoft" } } приведет к созданию документа

{
  "_id": "643f89b40441210c40b3448f",
  "_ip": "1.2.3.4",
  "_created": "2023-04-19T06:27:00.064Z",
  "_modified": "2023-04-19T06:27:00.064Z"
  "Name": "Tom",
  "Age": 38,
  "Company": {
    "Title": "Microsoft"
  },
}
Поиск документа в БД.
2.1. Поиск по идентификатору. Всегда возвращает один документ.

GET запрос https://racs.crmgroup.ru/v3/643f89b40441210c40b3448f?resource=aaa.bbb.xyz.com выдаст документ

{
  "_id": "643f89b40441210c40b3448f",
  "_ip": "1.2.3.4",
  "_created": "2023-04-19T06:27:00.064Z",
  "_modified": "2023-04-19T06:27:00.064Z"
  "Name": "Tom",
  "Age": 38,
  "Company": {
    "Title": "Microsoft"
  },
}
2.2. Поиск по фильтру. Всегда возвращает массив документов.

Поля поисковых запросов (необязательные, могут комбинироваться):

  • filter — объект, определяющий применяемый к результирующей выборке фильтр (описание), default: {}

Например, GET запрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com с телом {"filter":{ "Company.Title" : "Google" }, "limit": 0} выдаст документ вида

Или POST запрос https://racs.crmgroup.ru/v3/get?resource=aaa.bbb.xyz.com с телом {"filter":{ "Company.Title" : "Google" }, "limit": 0} выдаст документ вида

{
  "totalCount": 1,
  "documents": [
    {
      "_id": "643f940cfe579b0b077a0476",
      "_ip": "1.2.3.4",
      "_created": "2023-04-19T07:11:08.486Z",
      "_modified": "2023-04-19T07:11:08.486Z"
      "Name": "Alice",
      "Age": 33,
      "Company": {
        "Title": "Google"
      },
    }
  ]
}
  • sort — объект, определяющий порядок сортировки результирующей выборки (описание), default: { "_created", -1 }

Например, GET запрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com с телом {"sort": { "Company.Title": 1 , "Age": -1 }, "filter": {}, "limit": 0} выдаст документ вида

{
  "totalCount": 4,
  "documents": [
    {
      "_id": "643f940cfe579b0b077a0476",
      "_ip": "1.2.3.4",
      "_created": "2023-04-19T07:11:08.486Z",
      "_modified": "2023-04-19T07:11:08.486Z"
      "Name": "Alice",
      "Age": 33,
      "Company": {
        "Title": "Google"
      },
    },
    {
      "_id": "643f9314fe579b0b077a0474",
      "_ip": "1.2.3.4",
      "_created": "2023-04-19T07:07:00.985Z",
      "_modified": "2023-04-19T07:07:00.985Z"
      "Name": "Tom",
      "Age": 38,
      "Company": {
        "Title": "Microsoft"
      },
    },
    {
      "_id": "643f9413fe579b0b077a0477",
      "_ip": "1.2.3.4",
      "_created": "2023-04-19T07:11:15.837Z",
      "_modified": "2023-04-19T07:11:15.837Z"
      "Name": "Dan",
      "Age": 33,
      "Company": {
        "Title": "Microsoft"
      },
    },
    {
      "_id": "643f9405fe579b0b077a0475",
      "_ip": "1.2.3.4",
      "_created": "2023-04-19T07:11:01.679Z",
      "_modified": "2023-04-19T07:11:01.679Z"
      "Name": "Sam",
      "Age": 25,
      "Company": {
        "Title": "Microsoft"
      },
    }
  ]
}
  • limit — максимальное количество документов в результирующей выборке (описание), limit=0 — вывести все значения, default: 1.
  • skip — смещение от начала документов в результирующей выборке (описание), default: 0.

Например, указание {"skip": 200, "limit": 100} выдаст третью сотню элементов выборки документов.

2.3. Агрегированная выборка документов. Реализует операции агрегирования mongodb.

Поля запросов агрегирования:

  • aggregation — объект, определяющий этапы агрегирования, применяемые к результирующей выборке.

Например, GET запрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com и его тело:

{
  "aggregation": 
  { 
    "stages": 
    [
      {...}, 
      {...},
      ...
    ]
  }
}

где stages — это массив объектов Aggregation Pipeline Stages, например:

{"aggregation": 
  { 
    "stages":[
      {"$match": { "data.userId": "696b76253d3ee8053aa89901"}},
      {"$addFields": {"data.postId": { "$toObjectId": "$data.postId" }}},
      {"$lookup": {
        "from": "posts",
        "localField": "data.postId",
        "foreignField": "_id",
        "as": "post"
      }},
      {"$unwind": "$post"},
      {"$replaceRoot": { "newRoot": "$post" }}
  ]}
}

Поля ответов на поисковые запросы:

  • totalCount — общее количество найденных документов до применения limit и skip для п.2.2, общее количество документов для п.2.3.
  • documents — результирующая выборка документов.
Модификация документов в БД.
3.1. Модификация по идентификатору.

Поля запросов модификации:

  • update — объект, определяющий модификацию (описание)

Например, PATCH запрос https://racs.crmgroup.ru/v3/643f89b40441210c40b3448f?resource=aaa.bbb.xyz.com с телом {"update":{"$inc":{"Age":1}, "$set":{"Company.Title": "Google Inc."}}} выдаст документ вида

{
  "matchedCount": 1,
  "modifiedCount": 1
}
  • replace — объект, определяющий замену (описание)

Например, PATCH запрос https://racs.crmgroup.ru/v3/643f89b40441210c40b3448f?resource=aaa.bbb.xyz.com с телом {"replace":{"Name":"Test123"}} выдаст документ вида

{
  "matchedCount": 1,
  "modifiedCount": 1
}
  • options — для операций update и replace можно указать дополнительные опции: isUpsert = true|false.

Например, PATCH запрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com с телом {"replace":{"Name":"Tom"}, "options":{"isUpsert": true}} выдаст документ вида

{
  "matchedCount": 1,
  "modifiedCount": 1,
  "upsertedId": "64461dc4f722af48a2b79320"
}
3.2. Модификация по фильтру.

Поля запросов модификации:

  • filter — объект, определяющий фильтр, применением которого будет получена выборка объектов для модификации. Аналогичен п.2.2. Поиск по фильтру. Применение фильтра {} приведет к модификации всех документов БД! default: фильтр, возвращающий пустую выборку.
  • update — объект, определяющий модификацию. Аналогичен п.3.1. Модификация по идентификатору.

Например, PATCH запрос https://racs.crmgroup.ru/v3/643f89b40441210c40b3448f?resource=aaa.bbb.xyz.com с телом {"filter":{"Company.Title": "Microsoft"},"update":{"$inc":{"Age":1}, "$set":{"Company.Title": "Microsoft Inc."}}} выдаст документ вида

{
  "matchedCount": 3,
  "modifiedCount": 3
}
  • replace — объект, определяющий замену (описание). Фильтру должен удовлетворять только один документ!

Например, PATCH запрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com с телом {"replace":{"Name":"Tom"}} выдаст документ вида

{
  "matchedCount": 1,
  "modifiedCount": 1
}
  • options — для операций update и replace можно указать дополнительные опции: isUpsert = true|false.

Например, PATCH запрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com с телом {"replace":{"Name":"Tom"}, "options":{"isUpsert": true}} выдаст документ вида

{
  "matchedCount": 1,
  "modifiedCount": 1,
  "upsertedId": "64461dc4f722af48a2b79320"
}

Поля ответов на запросы модификации:

  • matchedCount- количество документов, удовлетворяющих фильтру.
  • modifiedCount- количество модифицированных документов.
Удаление документов из БД.
4.1. Удаление по идентификатору.

Например, DELETE запрос https://racs.crmgroup.ru/v3/643f89b40441210c40b3448f?resource=aaa.bbb.xyz.com выдаст документ вида

{
  "deletedCount": 1
}
4.2. Удаление по фильтру.

Поля запросов модификации:

  • filter — объект, определяющий фильтр, применением которого будет получена выборка объектов для удаления. Аналогичен п.2.2. Поиск по фильтру. Применение фильтра {} приведет к удалению всех документов БД! default: фильтр, возвращающий пустую выборку.

Например, DELETEзапрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com с телом {"filter":{"Company.Title": "Microsoft Inc."}} выдаст документ вида

{
  "deletedCount": 3
}

Поля ответов на запросы удаления:

  • deletedCount — количество удаленных документов.
Управление кэшем.

Управление кэшем включено всегда.

Запись в кэше создается в ходе выполнения операции чтения данных из БД (READ), при выполнении операций модификации (CREATE/UPDATE/DELETE) выполняется частичная инвалидация кэша (см. таблицу ниже).

Предусмотрена процедура полной очистки кэша для ресурса|dataset’а (см. параметр API /v3/clear-cache).

Использование тегов кэша (указаниеcacheTag=some-tag) позволяет синхронно управлять кэшем в нескольких dataset’ах. В операциях чтения из БД (READ) может быть указан только один тег (cacheTag=theTag), в операциях модификации (CREATE/UPDATE/DELETE) может быть указано несколько тегов через запятую (cacheTag=tag1,tag2,tag3).

Таблица соответствия ключей создаваемых/удаляемых записей кэша по типам операций:

(* — маска, соответствующая любому содержанию; | — условный разделитель полей для обеспечения корректности парсинга)

Операция 🡆Способ выполнения 🡇Read w/o tagCreate|Update|Delete w/o tagRead with tagCreate|Update|Delete with tag(s)(<tag> может быть списком тегов)
resource by id<resource>|id=<id><resource>|id=<id><resource>|filter=*<resource>|<tag>|id=<id><resource>|<tag>|id=<id><resource>|<tag>|filter=*
resource + dataset by id<resource>|<dataset>|id=<id><resource>|<dataset>|id=<id><resource>|<dataset>|filter=*<resource>|<tag>|id=<id><resource>|<tag>|id=<id><resource>|<tag>|filter=*
resource by filter<resource>|filter=<filter><resource>|id=*<resource>|filter=*<resource>|<tag>|filter=<filter><resource>|<tag>|*
resource + dataset by filter<resource>|<dataset>|filter=<filter><resource>|<dataset>|id=*<resource>|<dataset>|filter=*<resource>|<tag>|filter=<filter><resource>|<tag>|*
Пакетный режим.

Пакетный режим позволяет одним запросом к серверу выполнить несколько независимых операций.

Поля пакетных запросов:

  • process — объект, определяющий последовательность и содержащий параметры выполняемых операций, no default, представляет собой массив объектов вида
{
  "operation": "create|read|update|delete",
  "parameters": { тело запроса операции, если есть },
  "id": "идентификатор" // только для операций по идентификатору 
}

Ответ на пакетные запросы представляет собой переданный в качестве аргумента объект process с добавленным в объект каждой операции объект result:


{
  "operation": "create|read|update|delete",
  "parameters": { тело запроса операции, если есть },
  "id": "идентификатор" // только для операций по идентификатору 
  "result": { результат операции }
}

Например, BATCH запрос https://racs.crmgroup.ru/v3?resource=aaa.bbb.xyz.com с телом { "process" : [ { "operation": "create", "parameters": { "Hello": "World!" } }, { "operation": "create", "parameters": { "Hello2": "World2!" } } ] } выдаст документ вида

{
    "process": [
        {
            "operation": "create",
            "parameters": {
                "Hello": "World!"
            },
            "result": {
                "Hello": "World!",
                "_created": "2023-04-21T12:23:36.737Z",
                "_modified": "2023-04-21T12:23:36.737Z",
                "_id": "3bfb0c0cc3048e490eca2e95",
                "_ip": "1.2.3.4"
            }
        },
        {
            "operation": "create",
            "parameters": {
                "Hello2": "World2!"
            },
            "result": {
                "Hello2": "World2!",
                "_created": "2023-04-21T12:23:38.263Z",
                "_modified": "2023-04-21T12:23:38.263Z",
                "_id": "614adb20c3048e490eca2e96",
                "_ip": "1.2.3.4"
            }
        }
    ]
}

/v3/clear-cache

Всегда возвращает код 200. Выполняет очистку кэша для ресурса или dataset’а, если последний указан.

Параметры запроса:

Параметры url запроса:

  • resource (required) — ресурс. Ресурсом может быть сайт или проект, контрагент, это верхний уровень структуры данных. Если не передаётся явно, берётся из referer-параметра (hostname ограничивается именем домена второго уровня) запроса.
  • dataset — идентифицирует набор сущностей для разделения доступа. Если не передаётся явно, берётся из referer-параметра (путь текущей страницы) запроса.

Например, GET запрос https://racs.crmgroup.ru/v3/clear-cache?resource=aaa.bbb.xyz.com приведет к очистке всего кэша для ресурса aaa.bbb.xyz.com (для всех его dataset’ов, если они используются).

Содержание