Дизайн RESTful api, HATEOAS и обнаружение ресурсов

Одна из основных идей HATEOAS заключается в том, что клиенты должны иметь возможность запускаться с единого URL-адреса точки входа и обнаруживать все доступные ресурсы и переходы состояний, доступные для них. Хотя я прекрасно вижу, как это работает с HTML и человеком, стоящим за браузером, нажимающим на ссылки и кнопки «Отправить», меня спрашивают, как этот принцип можно применить к проблемам, с которыми мне (не) повезло иметь дело.

Мне нравится, как принцип дизайна RESTful представлен в статьях и образовательных статьях, где все имеет смысл. Как получить чашку кофе - хороший тому пример. Я постараюсь следовать соглашению и предложить простой и свободный от утомительных деталей пример. Давайте посмотрим на почтовые индексы и города.

Проблема 1

Допустим, я хочу разработать RESTful api для поиска городов по почтовым индексам. Я использую ресурсы под названием «города», вложенные в почтовые индексы, так что GET на http://api.addressbook.com/zip_codes/02125/cities возвращает документ, содержащий, скажем, две записи, которые представляют Дорчестер. и Бостон.

У меня вопрос: как такой URL можно найти с помощью HATEOAS? Вероятно, непрактично выставлять индекс всех ~ 40K почтовых индексов в http://api.addressbook.com/zip_codes .Даже если индекс элементов в 40 КБ не является проблемой, помните, что я придумал этот пример, и существуют коллекции гораздо большего размера.

По сути, я хотел бы предоставить не ссылку, а шаблон ссылки, а, скорее, вот так: http://api.addressbook.com/zip_codes/ {: zip_code} / cities , и что идет вразрез с принципами и полагается на внеполосные знания, которыми обладает клиент.

Проблема 2

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

• GET on http://api.addressbook.com/cities?name=X вернет только города с названиями, соответствующими X .

• GET on http://api.addressbook.com/cities?min_population=Y вернет только города с населением, равным или превышающим Y .

Конечно, эти два фильтра можно использовать вместе: http://api.addressbook.com/cities?name=X&min_population=Y .

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

Итак, как принципы, лежащие в основе HATEOAS, могут помочь сделать такой тривиальный API действительно RESTful?