Дизайн URL для API

Question

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

Мы не уверены, какой дизайн URL использовать ... мы думаем о:

• / users.json? Per_page = 10 & = объединение частей, прослушивание и parts_per_page = 5 & auditions_per_page = 5

  * * 1 010

• / users.json? Per_page = 10 & ассоциация [] = & части ассоциации [] = & прослушивания parts_per_page = 5 & auditions_per_page = 10

• / users.json? Per_page = 10 & ассоциации [прослушивания] = TRUE и ассоциация [части] [per_page] = 5

Что ты думаешь? какой бы вы выбрали? Зачем ? один из них не похож на действительные схемы URL?

Спасибо!

Answer 1

Мой ответ: /users.json.HTTP оптимизирован для крупномасштабной передачи гипермедиа;кэширование является большой частью этого, и ни одна из схем URI, приведенных выше, не очень удобна для кэширования.

Squid, например, является популярным HTTP-кешем, который по умолчанию не кэширует ни один URL, которыйимеет строку запроса.Кроме того, многие клиенты и даже серверы и посредники генерируют и принимают параметры строки запроса в неопределенном порядке;то есть «? a = 3 & b = 5» может быть произвольно переписано как «? b = 5 & a = 3».Однако для HTTP-кэширования порядок имеет значение, и две страницы будут кэшироваться отдельно, даже если они имеют одинаковое содержимое.Когда вы добавляете параметры, эта проблема возрастает экспоненциально.

Вы должны спроектировать свои ресурсы (и их представления), чтобы использовать преимущества кэширования двумя противоположными, но дополнительными методами:

1. Объедините фрагментированные и частичные представления в более крупные унифицированные представления и
2. Разделите большие унифицированные представления на более мелкие представления вдоль границ кэша (которые, как правило, являются границами транзакций), но связаны гиперссылками.

В вашем случае шаг 1 подразумевает объединение ассоциаций и частей в представление «пользователи», без какой-либо опции для клиента, чтобы настроить, какие и сколько.Это позволит вам активно кэшировать представление с одним ответом, не перегружая ваши (и их) кэши комбинаторным взрывом ответов из-за всех параметров строки запроса.

Шаг 2 подразумевает разделение /users.json на отдельного «пользователя»сущности, каждая из которых имеет ресурс "ассоциации" и ресурс "части".Так /users/{id} и /users/{id}/associations и /users/{id}/parts.Затем ресурс "/ users" возвращает массив гиперссылок на отдельные ресурсы "/ users / {id}", и каждое представление "/ users / {id}` "содержит гиперссылки на его ассоциации и части (эта часть более гибкая -- оно может лучше подойти вашему приложению для непосредственного встраивания ассоциаций и частей в пользовательский ресурс. Это позволит вам агрессивно кэшировать ответ для каждого «востребованного» ресурса без необходимости кэшировать всю базу данных.

Тогда ваши пользователи будут кричать «но это в 10 раз больше сетевого трафика!» На что вы спокойно отвечаете: «Нет, это 1/10 сетевого трафика, потому что 9 раз из 10 запрошенных ресурсов уже находятся на вашей стороне клиента (кэш браузера (и когда их нет, это 1/10 вычислительных ресурсов сервера, так как они находятся в кэше на стороне сервера, а когда их нет, мы избегаем штамповки с помощью интеллектуального кэша на сервере). "

Конечно, если ресурс /users - это миллион новых посещенийторы бьют каждый день, тогда ваш путь оптимизации может быть другим.Но это не похоже на ваши примерные схемы URI.

Answer 2

В теге restful-url есть много полезных сообщений.

Несколько полезных постов:

Должны ли URL REST API выглядеть следующим образом?

Рекомендации по использованию URI в качестве значения параметра в вызовах REST.

Как создать REST URL без глаголов?

Answer 3

Я бы пошел на 1-й. Мне не нравится видеть нотацию [] в URL, ИМХО, это затрудняет использование и понимание клиентом. Несколько изменений в качестве предложений.

1) Поскольку ассоциация кажется массивом, измените ассоциации (множественное число, если я прав, и это массив)

2) Вы также можете попробовать добавить per_page по умолчанию и необязательный, даже агрегирующий, что-то вроде per_page_parts_auditions вместо того, чтобы использовать per_page_parts и per_page_auditions. Я бы не стал этого делать, если бы ваш API был спроектирован как общедоступный, так как его проще использовать, но труднее понять, но, как вы разместили, он является частным ... это хороший способ избежать репликации.