Лучший способ управлять фильтрами в коллекции

У меня есть три операции с коллекциями на одном ApiResource, у которых есть разные normalization_context и filters.

  • /equipments Получить все оборудование (отфильтровано по текущему пользователю)
  • /equipments/A Получить все оборудование, соответствующее правилам A
  • /equipments/B Получить все оборудование, соответствующее правилам B

Некоторые фильтры устанавливаются на вложенные свойства (идентификаторы связанных сущностей). Я хочу дать потребителю API значения, которые он может использовать для определенных фильтров. Допустим, у меня есть фильтр компании, общий для всех конечных точек.

  • Для /equipments допустимые значения: 1,2,3
  • Для /equipments/A допустимые значения: 4,5,6
  • Для /equipments/B допустимые значения: 1,3,5.

Решение, которое я вижу, - добавить .../filters конечную точку для каждой операции, которая будет возвращать фильтры с разрешенными значениями.

GET /equipments/filters

[
    {
        'name': 'company',
        'type': integer,
        'choices': [
            'Company 1': 1,
            'Company 2': 2,
            'Company 3': 3,
        ]
    },
    {
        'name': 'operator',
        'type': autocomplete,
        'url': /equipments/filters/operator?q={q}
    }
]

Дополнительный вопрос: если это хорошее решение, где и как я могу добавить эти операции в документацию JSON-LD / Hydra?


collections symfony api-platform.com
person Erwan    schedule 23.08.2017    source источник

Ответы (1)


arrow_upward
1
arrow_downward

Большинство форматов документации API, включая Swagger и JSON-LD (поддерживаемые платформой API), позволяют указывать допустимое значение для фильтров без необходимости делать что-то особенное.

В Swagger вы можете использовать свойство enum объекта parameter для определения допустимых значений: https://swagger.io/docs/specification/2-0/enums/

paths:
  /equipments/B:
    get:
      parameters:
        - in: query
          name: company
          description: A company filter
          type: integer
          enum: [1, 3, 5]

Если вы предпочитаете использовать Hydra, вы можете использовать шаблонные ссылки для достижения желаемого:

{
  "@context": "http://www.w3.org/ns/hydra/context.jsonld",
  "@type": "IriTemplate",
  "template": "/equipments/B{?company}",
  "mappings": [
    {
      "@type": "IriTemplateMapping",
      "variable": "company",
      "property": "http://example.com/myCompanyType"
    }
  ]
}

Затем вам нужно возвращать значения либо динамически, добавляя конечную точку, возвращающую применимые значения, либо непосредственно в словаре в словаре, если список статический (например, http://schema.org/ActionStatusType).

Чтобы добавить такую ​​информацию в платформу API, вам необходимо украсить встроенные службы, генерирующие документацию. Пример для Swagger: https://github.com/api-platform/docs/blob/master/core/swagger.md#override-swagger-documentation.

person Kévin Dunglas    schedule 23.08.2017
comment
Я читал о шаблонных ссылках в спецификации Hydra. Но я не вижу, где добавить конечную точку для применимых значений. - person Erwan; 23.08.2017
comment
Вы можете просто поместить его IRI в значение property. - person Kévin Dunglas; 23.08.2017
comment
Так что это может быть разным для каждой /equipements конечной точки, кажется, хорошо. Однако не совсем оптимально с точки зрения производительности сети. Чтобы отобразить список с фильтрами, вам нужно будет сделать дополнительный запрос для каждого фильтра. - person Erwan; 23.08.2017
comment
вы можете включить несколько коллекций в один документ JSON-LD. Формат очень гибкий - person Kévin Dunglas; 23.08.2017
comment
Не знаю, что смогу! Я все еще новичок в REST API :) Спасибо за помощь - person Erwan; 23.08.2017
comment
Хм, я не нашел для этого подходящего синтаксиса. Включаю ли я коллекцию непосредственно в свойство (json-ld.org/spec/ последнее / json-ld / # встраивание)? - person Erwan; 23.08.2017