Общие сведения

Конфигурирование сервисов осуществляется при помощи настройки метаданных. Метаданные представляют собой json, описывающий, какие объекты должны быть созданы, какие атрибуты описывают их и какие связи имеются между объектами. Каждому объекту соответствует таблица в базе данных. Метаданные позволяют привести состояние таблиц БД к единой структуре:

  • если таблица в базе данных отсутствует, то она будет создана;
  • если в таблице отсутствуют необходимые атрибуты, то они будут добавлены.

Описание простого объекта

Каждый объект, добавляемый с помощью метаданных, описывается следующими параметрами:

  • name – имя объекта;
  • key – атрибут объекта, содержащий уникальный ключ записи;
  • cas – признак, определяющий, применять ли к данному объекту оптимистичное блокирование;
  • fields – массив атрибутов, описывающих данный объект. По каждому атрибуту может быть задан:
    • name – имя атрибута;
    • type – тип атрибута, возможны значения number (число), string (строка), bool (булевый тип), array (массив) и object (объект);
    • optional – признак обязательности атрибута;
    • default (опционально) – правило задания значения по умолчанию (в этом случае признак optional должен иметь значение true).

Пример метаданных:

{
    "name": "person",
    "key": "id",
    "cas": true,
    "fields": [{
        "name": "id",
        "type": "number",
        "optional": true,
        "default": {
            "func": "nextval"
        }
    }, {
        "name": "name",
        "type": "string",
        "optional": false
    },{
        "name": "gender",
        "type": "string",
        "optional": false
    },{
      "name": "cas",
      "type": "number",
      "optional": false
    }]
}

Эти метаданные создают объект person. Записи будут доступны по ссылке /person/{id}, где id – это идентификатор записи.

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

Описание связей между объектами

При добавлении объекта можно указать, с какими другими объектами он связан. Например, адрес или документ может относиться к конкретному человеку, сотрудник – к организации. Для создания такого «зависимого» объекта создаются метаданные, аналогичные простому объекту, но один из атрибутов объекта (fields) должен содержать описание ссылки. Описание ссылки содержит параметры:

  • name – имя атрибута (ссылки);
  • type – тип атрибута (может принимать значение “object” или “array” – в зависимости от того, может ли данный объект быть связан с одним или несколькими объектами);
  • optional – признак обязательности атрибута;
  • linkMeta – имя объекта, с которым связан данный объект;
  • linkType – тип ссылки, может принимать значения:

    • inner – ссылка производится на внутренний объект, от которого зависит данный объект (например, у «адреса» ссылка на «физическое лицо» будет этого типа);
    • outer – ссылка производится на внешний, зависимый объект. Например, у «физического лица» ссылка на «адрес» будет этого типа;
  • outerLinkField – атрибут внешнего объекта, в котором содержатся идентификаторы данного объекта (только для linkType=outer).

В качестве примера приведем метаданные адреса, который содержит в себе ссылку на объект person:

{
    "name": "address",
    "key": "id",
    "cas": true,
    "fields": [{
        "name": "id",
        "type": "number",
        "optional": true,
        "default": {
            "func": "nextval"
        }
    }, {
        "name": "country",
        "type": "string",
        "optional": false
    },{
        "name": "zipcode",
        "type": "string",
        "optional": true
    },{
        "name": "street",
        "type": "string",
        "optional": false
    }, {
        "name": "person",
        "type": "object",
        "optional": false,
        "linkMeta": "person",
        "linkType": "inner"
    },{
      "name": "cas",
      "type": "number",
      "optional": false
    }]
}

При добавлении этих метаданных объект, указанный в linkMeta, должен существовать. В приведенном примере можно сконфигурировать объект с адресами, если ранее создан объект person. Однако добавление этих метаданных автоматически не приведет к тому, что во внутреннем объекте (в приведенном примере – person) не появятся ссылки на зависимый объект. Чтобы они появились, необходимо добавить в метаданные внутреннего объекта атрибут:

  • name – имя атрибута;
  • type – тип атрибута, должен принимать значение “object” (связь один к одному) или “array” (один ко многим);
  • optional – признак обязательности атрибута;
  • linkMeta – имя объекта, с которым связан данный объект;
  • linkType – тип ссылки, должен принимать значение “outer”:
  • outerLinkField – атрибут внешнего объекта, в котором содержатся идентификаторы данного объекта.

Пример метаданных такого объекта:

{
    "name": "person",
    "key": "id",
    "cas": true,
    "fields": [{
        "name": "id",
        "type": "number",
        "optional": true,
        "default": {
            "func": "nextval"
        }
    }, {
        "name": "name",
        "type": "string",
        "optional": false
    },{
        "name": "addresses",
        "type": "array",
        "optional": true,
        "linkMeta": "address",
        "outerLinkField": "person",
        "linkType": "outer"
    },{
       "name": "cas",
       "type": "number",
       "optional": false
    }]
}

Таким образом, чтобы сконфигурировать конструкцию из двух связанных объектов, необходимо выполнить операции:

  1. Создать главный объект (в нашем примере – person).

  2. Создать зависимый объект (в нашем примере – address), в котором будет ссылка на внутренний объект.

  3. Изменить метаданные главного объекта, указав в нем ссылки (одну или массив) на зависимый объект.

Создание/изменение метаданных

Для сохранения, изменения и удаления метаданных предусмотрены REST-сервисы Blitz REST API Server.

Для создания метаданных необходимо выполнить запрос по адресу <hostname>/meta методом PUT, в котором:

  • <hostname> – адрес сервиса Blitz REST API Server. Например: http://localhost:8080/api;
  • заголовок Content-Type должен иметь значение “application/json”;
  • в теле запроса указан json с описанием метаданных.

Пример создания записи:

PUT /api/meta HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "person",
    "key": "id",
    "cas": true,
    "fields": [{
        "name": "id",
        "type": "number",
        "optional": true,
        "default": {
            "func": "nextval"
        }
    }, {
        "name": "name",
        "type": "string",
        "optional": false
    },{
        "name": "gender",
        "type": "string",
        "optional": false
    },{
      "name": "cas",
      "type": "number",
      "optional": false
    }]
}

После создания метаданных Blitz REST API Server сохраняет файл с метаданными в директорию, из которой запущен сервер. Имя файла соответствует имени созданного объекта.

Для изменения метаданных необходимо выполнить запрос по адресу <hostname>/meta/<object> методом POST, в котором:

  • <hostname> – адрес сервиса Blitz REST API Server. Например: http://localhost:8080/api;
  • <object> – объект, который требуется изменить;
  • заголовок Content-Type должен иметь значение “application/json”;
  • в теле запроса указан json с описанием измененных метаданных.

Пример добавления в метаданные объекта person сведений об адресах:

POST /api/meta/person HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Cache-Control: no-cache

{
    "name": "person",
    "key": "id",
    "cas": true,
    "fields": [{
        "name": "id",
        "type": "number",
        "optional": true,
        "default": {
            "func": "nextval"
        }
    }, {
        "name": "name",
        "type": "string",
        "optional": false
    },{
        "name": "gender",
        "type": "string",
        "optional": false
    },{
        "name": "addresses",
        "type": "array",
        "optional": true,
        "linkMeta": "address",
        "outerLinkField": "person",
        "linkType": "outer"
    },{
      "name": "cas",
      "type": "number",
      "optional": false
    }]
}

Для удаления метаданных объекта необходимо выполнить запрос по адресу <hostname>/meta/<object> методом DELETE, в котором:

  • <hostname> – адрес сервиса Blitz REST API Server. Например: http://localhost:8080/api;
  • <object> – объект, который требуется удалить.

Пример запроса, позволяющего удалить метаданные объекта person:

DELETE /api/meta/person HTTP/1.1
Host: localhost:8080
Cache-Control: no-cache
Postman-Token: 2a51a4ca-3f2c-2e7c-b373-6658cb2e7df9