Комментарии 5
Робот на иллюстрации растерянно смотрит на читателя – как из предложенных деталей шуруповертом с буром от перфоратора и отвёрткой собрать API?
Есть вопросы:
1. Почему вы решили использовать формат /v1/users/<username>/update_email для обновления поля, а не PUT или PATCH запрос на /v1/users/ как это обычно делается в rest? Тоже самое для update_extension_number, update_email, voice_mail_box_on, voice_mail_box_off
2. Непонятно зачем данные в ответе сервера обернуты в объект со статусом и сообщением — {«status»: «error», «message»: «some_error», «data»: null}. status может быть либо error, либо success, и это можно понять по коду ответа 2хх — success, 4хх и 5хх — error.
3. У вас создание пользователя делается при помощи POST запроса на /v1/users/create. По REST это обычное делается POST запросом на /v1/users. Вот создание звонка у вас так и делается — POST запросом на /v1/calls. Вы уж определитесь)
4. /v1/calls/complete и /v1/calls/active как будто можно было сделать как /v1/calls?status=complete и /v1/calls?status=active, при этом /v1/calls возвращал бы все звонки
1. Почему вы решили использовать формат /v1/users/<username>/update_email для обновления поля, а не PUT или PATCH запрос на /v1/users/ как это обычно делается в rest? Тоже самое для update_extension_number, update_email, voice_mail_box_on, voice_mail_box_off
2. Непонятно зачем данные в ответе сервера обернуты в объект со статусом и сообщением — {«status»: «error», «message»: «some_error», «data»: null}. status может быть либо error, либо success, и это можно понять по коду ответа 2хх — success, 4хх и 5хх — error.
3. У вас создание пользователя делается при помощи POST запроса на /v1/users/create. По REST это обычное делается POST запросом на /v1/users. Вот создание звонка у вас так и делается — POST запросом на /v1/calls. Вы уж определитесь)
4. /v1/calls/complete и /v1/calls/active как будто можно было сделать как /v1/calls?status=complete и /v1/calls?status=active, при этом /v1/calls возвращал бы все звонки
1. Мы сознательно отказались в своем API от использования любых методов, кроме GET и POST, чтобы избежать возможных проблем. Дискуссию на эту тему можно посмотреть здесь. Если вкратце, то может случиться ситуация, когда криво настроенный прокси-сервер проглотит методы типа PUT или DELETE (http://habrahabr.ru/post/181988/#comment_6366880).
Или попадется клиент, который кроме GET и POST, ничего посылать не умеет (http://habrahabr.ru/post/181988/#comment_6369042).
Прецеденты уже были: http://stackoverflow.com/questions/2061898/urlrequest-with-delete-method
2. По поводу статуса — это сделано больше для наглядности, чтобы можно было оценить результат запроса без обращения к значению статусу кода. А в message содержится подробная причина ошибки, которая не всегда соответствует прямому описанию HTTP кода. Например, сообщения в случае, если в запросе вообще не указан ключ API и в случае, когда указан не существующий ключ, будут разные, но код ответа один — 403.
3. Здесь дело в том, что для пользователей в будущем планируется метод удаления. А поскольку мы отказались от метода DELETE, то единственным вариантом остается это сделать через
4. Мы не планировали смешивать в одной выдаче активные и совершенные звонки. Поэтому у нас нет GET-метода для /v1/calls.
По поводу /v1/calls?status=complete и /v1/calls?status=active — да, можно было сделать так. Здесь решили так не делать, чтобы избежать путаницы. Дело в том, что для совершенных запросов можно указать фильтр по номеру телефона и/или количеству дней за которые запрашиваются данные. Для активных же звонков данные фильтры не используются. Поэтому, решили использовать разные URL.
Или попадется клиент, который кроме GET и POST, ничего посылать не умеет (http://habrahabr.ru/post/181988/#comment_6369042).
Прецеденты уже были: http://stackoverflow.com/questions/2061898/urlrequest-with-delete-method
2. По поводу статуса — это сделано больше для наглядности, чтобы можно было оценить результат запроса без обращения к значению статусу кода. А в message содержится подробная причина ошибки, которая не всегда соответствует прямому описанию HTTP кода. Например, сообщения в случае, если в запросе вообще не указан ключ API и в случае, когда указан не существующий ключ, будут разные, но код ответа один — 403.
3. Здесь дело в том, что для пользователей в будущем планируется метод удаления. А поскольку мы отказались от метода DELETE, то единственным вариантом остается это сделать через
url: /v1/users/create и /v1/users/delete
4. Мы не планировали смешивать в одной выдаче активные и совершенные звонки. Поэтому у нас нет GET-метода для /v1/calls.
По поводу /v1/calls?status=complete и /v1/calls?status=active — да, можно было сделать так. Здесь решили так не делать, чтобы избежать путаницы. Дело в том, что для совершенных запросов можно указать фильтр по номеру телефона и/или количеству дней за которые запрашиваются данные. Для активных же звонков данные фильтры не используются. Поэтому, решили использовать разные URL.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
API RingCloud, всё только начинается