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?



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

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

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

Тогда однозначно 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 ★★
()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.