Укажите количество элементов или все элементы в запросе REST API. - PullRequest
Новая
       23

Укажите количество элементов или все элементы в запросе REST API.

0 голосов
/ 14 апреля 2020

Я разрабатываю API и задаюсь вопросом, как лучше использовать значения, в которых можно указать число или список элементов, или просто указать, что это «все» этих элементов.

Например, представьте себе конечная точка / анализ, которая позволяет анализировать документ для определенных c категорий. Пример запроса может быть следующим: 

{
   "documentId": "my-doc",
   "numberOfLines": 100,
   "categories": ["category1", "category2"]
}

Как лучше всего указать, что мне нужны все строки и все категории? Наличие нескольких типов для одного и того же значения выглядит следующим образом: 

{
    "documentId": "my-doc",
    "numberOfLines": "all",
    "categories": "all"
}

Лучше ли иметь что-то вроде null или -1, обозначающее все. Мне это не нравится, потому что это может привести к ошибкам, если обработчик пропустит эту логику c: 

{
    "documentId": "my-doc",
    "numberOfLines": null, //null to mean all
    "categories": null // null to mean all
}

Ответы [ 2 ]

1 голос
/ 26 апреля 2020

Не думаю, что здесь что-то не так с использованием строки all. Системы типов, такие как Typescript, и системы валидации, такие как JSON Schema, могут легко express это, и это намного более информативно, чем пустой массив, -1 или null.

Использование кодов, подобных -1 это что-то вроде пережитка прежних времен, когда было важно сохранить несколько байтов, но трудно понять, что это могло бы означать. Еще одна очевидная альтернатива - звездочка *.

0 голосов
/ 14 апреля 2020

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

{
   "documentId": "my-doc",
}

будет правильным запросом и будет работать так же, как 

{
   "documentId": "my-doc",
   "numberOfLines": null, //null to mean all
   "categories": null // null to mean all
}
* 1006. * С другой стороны, если вы хотите, чтобы клиенты по умолчанию ограничивали полезную нагрузку только с особыми случаями, когда кто-то может захотеть, чтобы все данные были ИМХО, в этот файл вводятся слова "magi c words", например 
{
   "documentId": "my-doc",
   "numberOfLines": "IReallyReallyWantAllData",
   "categories": "IReallyReallyWantAllData"
}
...