===== Vendor API =====

На данной странице содержится общая информация по Vendor API. Связанные разделы: \\
  * [[ru:vendor-api:methods|]] \\
  * [[ru:vendor-api:contracts|]] \\
  * [[ru:vendor-api:errors|]] \\
  * [[ru:vendor-api:guids|]] \\
  * [[ru:vendor-api:dates|]] \\
  * [[ru:vendor-api:dynamic-properties|]] \\
  * [[ru:vendor-api:addons|]] \\
  * [[ru:vendor-api:glossary|]] \\
==== Решаемые задачи ==== 
Сервис позволяет выполнять CRUD операции над сущностями "подписка" и "подписчик"("пользователь") на стороне вендора.
==== Архитектурные принципы ==== 
[[https://habrahabr.ru/post/38730/|Архитектура REST]] \\
[[https://habrahabr.ru/post/181988/|Разработка web API]]\\
[[http://interosite.ru/articles/rest-api-design|Построение эффективной архитектуры RESTful API]] \\
[[https://geemus.gitbooks.io/http-api-design/content/index.html|HTTP API Design Guide]] \\
[[https://msdn.microsoft.com/en-us/library/partnercenter/dn974944.aspx|CREST API Reference]] \\
==== Авторизация ==== 
Basic/Digest/OAuth. Обсуждаемо, как и соединение по HTTPS. 

==== Заголовки запроса ====
Каждый HTTP-запрос к сервису обязан содержать следущий набор метаинформации в заголовках: \\
^ Имя ^ Тип ^ Описание ^
| Content-Type | string | application/json |
| vendor-api-tracking-id | string (GUID) | Уникальный идентификатор пары "запрос-ответ" для обеспечения идемпотентности (эквивалентности результатов повторяемого действия). В случае коммуникационных проблем (разрыв соединения, timeout) повторный запрос должен включать **тот же** GUID. При получении ответа на клиенте, данное значение идентификатора не может быть использовано клиентом еще раз. |
| vendor-api-correlation-id | string (GUID) | Уникальный идентификатор запроса. Каждый запрос к сервису должен обладать уникальным значением данного идентификатора, независимо от того, был ли получен ответ. Применяется для записи в логах, журналах ошибок.|
| vendor-api-version | string | Версия API | 

==== Заголовки ответа ====
Каждый HTTP-ответ сервиса обязан содержать следущий набор метаинформации в заголовках: \\
^ Имя ^ Тип ^ Описание ^
| Content-Type | string | application/json |
| vendor-api-version | string | Версия API | 
==== Действия над ресурсом ==== 
Типовые действия над ресурсом (URI) согласуются с методом HTTP-запроса:
^ Метод ^ Действие над ресурсом ^
| GET | Прочитать | 
| POST | Создать | 
| PUT | Обновить | 
| DELETE | Удалить |
Данные в теле запроса/ответа передаются в формате JSON. \\

==== Результат запроса ==== 
Успех/неуспех запроса определяется согласно стандартным HTTP-кодам ответа: \\
  * 200 ОК — все в порядке \\
  * 4хх — неправильный запрос / ошибка валидации входных данных \\
  * 5хх — ошибка сервера \\
В случае ошибки (коды 4хх-5хх) в теле ответа возвращается общий для сервиса набор данных, содержащий сообщение об ошибке и дополнительную информацию. Дополнительная информация в разделе 
[[ru:vendor-api:errors]].