LINUX.ORG.RU

REST(ful) API best practices

 ,


1

2

Пишу клиент-серверную программу и читаю всякие советы по проектированию REST API.

Есть 2 вида запросов, возвращающих JSON:

http://example.com/calendar/2014/april/1    # день
http://example.com/calendar/2014/april      # массив дней

Вопрос в том, что делать с запросами:

http://example.com/calendar/2014
http://example.com/calendar

Приходят в голову варианты:

  • Возвращать массив или хеш месяцев и лет.
  • Возвращать массив идентификаторов месяцев и лет (без содержимого).
  • Возвращать 404.

В статьях советуют первый вариант, но смущает, что:

  • Эти запросы не нужны в текущих сценариях.
  • Эти запросы будут возвращать большой объем данных.

Как это решают в хороших API?


В статьях советуют первый вариант, но смущает, что:

  • Эти запросы не нужны в текущих сценариях.
  • Эти запросы будут возвращать большой объем данных.

Тогда однозначно 2.

Minoru ★★★ ()

Если эти запросы действительно не нужны, то естественно нет смысла их реализовывать.

Hater ★★ ()
Ответ на: комментарий от Minoru

Тогда однозначно 2.

А есть примеры каких-нибудь открытых API, где так сделано?

gv ()

Раз не нужна, то не надо. Вам шашечки или ехать?

Думаю, вам важнее работающий функционал, чем соответствие неким «best practises».

BattleCoder ★★★★★ ()

лучше 404, пока не понадобится. best practices на 100% применимы только к публичным api. к внутренним - это только рекомендации

MyTrooName ★★★★★ ()
Последнее исправление: MyTrooName (всего исправлений: 1)

Hater, BattleCoder, MyTrooName, в варианте с 404 не нравится, что URL /a/b/c работает, а /a/b нет.

С реализацией функциональности проблем нет, так что мне в общем-то шашечки.

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

gv ()

А зачем тебе именно такая структура урла?

Почему не /calendar/2014-4-1 и /calendar/2014-4, соответственно, или как-то так?

Apple-ch ★★ ()
Ответ на: комментарий от Apple-ch

Почему не /calendar/2014-4-1 и /calendar/2014-4, соответственно, или как-то так?

О, точно, даже в голову не пришло!

gv ()
Ответ на: комментарий от gv

5xx - это ошибка сервера, а здесь ошибка клиента, ибо нефиг лазить куда не просят

anonymous ()

а по поводу

http://example.com/calendar

здесь все просто: делаем лимит на количество данных в ответе,и прикручиваем pagination, всёравно если данных много, нефиг их давать все юзеру

anonymous ()
Ответ на: комментарий от anonymous

5xx - это ошибка сервера, а здесь ошибка клиента, ибо нефиг лазить куда не просят

Ясно.

делаем лимит на количество данных в ответе,и прикручиваем pagination, всёравно если данных много, нефиг их давать все юзеру

Про pagination читал, да.

gv ()
Ответ на: комментарий от gv

API будет открытое у небольшой открытой программы

тада делай список месяцев/лет

MyTrooName ★★★★★ ()
Ответ на: комментарий от gv

Можно и вовсе 400. Не вижу особо принципиальной разницы. Главное на стороне клиента это правильно решить.

404 нужно возвращать в том случае, если в общем случае метод что-то должен возвращать, но для конкретного параметра возвращать нечего. Например, несуществующая страница.

Например, http://example.com/calendar/2014/february/30

BattleCoder ★★★★★ ()
Ответ на: комментарий от gv

Если уж так, я бы назвал GET /one одним методом, а GET /one/two - другим. Может, я и не прав.

BattleCoder ★★★★★ ()

http://example.com/calendar

Можно так: если год не указан, значит по умолчанию - текущий, или форма с выбором года если не лень, но проще по дефолту.

Фактически это типа «индексная страница календаря» - конечно новости не стоит там писать, но всегда можно предложить что-то полезное.

swwwfactory ★★ ()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.