Названия API для ограничения результатов?

Question

В нашем офисе у нас идут горячие дискуссии по поводу именования некоторых аргументов в нашем публичном API.

Везде, где мы предоставляем геттеры в какие-либо списки, мы хотим иметь возможность ограничивать результаты (для разбивки на страницы).

Т.е.: getPosts/getNews/getUsers/.../ должен иметь возможность вернуть предметы от 0 до 25, от 50 до 100 и т. Д. Итак, нам нужны два параметра. Первый параметр - это то, где мы начинаем, а второй - то, где мы заканчиваем.

Итак, должен ли второй параметр быть абсолютным или относительным? (Должны ли 50,75 вернуть предметы 50-75 или 50-125?)

Мы определились с относительным, поэтому второй параметр сообщает нам, сколько элементов нужно вернуть.

Хитрая часть называет это ясным и последовательным образом. Те, которые мы придумали до сих пор:

Первый:

start/index/offset/page/pageindex

Второе:

amount/count/maxcount/limit/perpage/pagesize

У каждого предложения есть свои плюсы и минусы. Использование «страницы» сделает неясным, начинается ли оно с 0 или 1. Использование «index» или «offset» будет более понятным в этом отношении, но более техническим (в конце концов, пользователи используют это для нумерации страниц в 99% время).

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

Answer 1

Я бы пошел на родственника, легче понять.

относительно именования: Мне нравится «начало» для первого результата и «количество» для количества результатов.

(но разве вы не смешиваете количество страниц и результатов?)

Answer 2

Я бы пошел с

getPosts(startIndex, count)

Answer 3

Определенно иди относительно. Я бы назвал их «индекс» и «считать». Обычно я бы использовал «длину», но она не подходит для того, что вы описываете. Если вы хотите сделать его похожим на linq, вы можете вызвать параметры «skip» и «take». Эти термины также более доступны для парня из Joe Average, который будет смотреть на полученный URL.