Как стать автором
Обновить

Комментарии 5

Робот на иллюстрации растерянно смотрит на читателя – как из предложенных деталей шуруповертом с буром от перфоратора и отвёрткой собрать API?
По итогу-то всё у него получилось :)
Ну вообще мы не подразумевали особой смысловой нагрузки в картинке :) хотя реализация 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. Мы сознательно отказались в своем 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, то единственным вариантом остается это сделать через
url: /v1/users/create и /v1/users/delete
. Для звонков же операция удаления бессмысленна, поэтому можно ограничиться POST запросом на /v1/calls, который позволит совершить звонок.

4. Мы не планировали смешивать в одной выдаче активные и совершенные звонки. Поэтому у нас нет GET-метода для /v1/calls.
По поводу /v1/calls?status=complete и /v1/calls?status=active — да, можно было сделать так. Здесь решили так не делать, чтобы избежать путаницы. Дело в том, что для совершенных запросов можно указать фильтр по номеру телефона и/или количеству дней за которые запрашиваются данные. Для активных же звонков данные фильтры не используются. Поэтому, решили использовать разные URL.
Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.