↓Перейти к содержанию
  1. Архив/

Организация API веб-служб. Ulcamp::Dev

·4 минуты·

До того момента, пока перед нами не встает задача работы с API какого-либо сервиса, мы не задумываемся о том, как его правильнее организовать…

Да, это так… Мы не задумываемся над этим вопросом, когда проектируем API для своего сервиса, если не занимались этим ранее и не наступили на грабли фидбека недовольных пользователей.

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

Вот о том, как упростить жизнь разработчикам и пойдет речь.

Веб-служба #

Для начала давайте определимся, что такое веб-служба. Как-то так получилось, что данный термин люди понимают по разному и о того, как его понимать можно по разному понимать то, о чем и пойдет речь.

  • Итак, веб-служба, веб-сервис (англ. web service) — идентифицируемая конкретным адресом (домен, ип) программная система со стандартизированными интерфейсами.
  • Веб-службы могут взаимодействовать друг с другом и со сторонними приложениями посредством сообщений, основанных на определённых протоколах (SOAP, XML-RPC и т. д.).
  • Веб-служба является единицей модульности при использовании сервис-ориентированной архитектуры приложения.
  • В обиходе веб-сервисами называют услуги, оказываемые в Интернете. В этом употреблении термин требует уточнения, идёт ли речь о поиске, веб-почте, хранении документов, файлов, закладок и т. п. Такими веб-сервисами можно пользоваться независимо от места доступа в Интернет, компьютера или браузера.
  • Как видите, можно сказать по разному, мы сделаем на том, что веб службой будем считать …

API #

  • Что такое API?
  • Определение API

Нет проблем? Сейчас придумаем! #

Давайте представим, у вас есть сайт, на котором вы кропотливо, изо дня в день, собираете информацию о происходящих в вашем городе мероприятиях. Не важно как вы это делает, сами ли ручками бегаете по сайтам и собираете анонсы, или же вы написали скрипт, который за вас выполняет эту работу, важно то, что эта информация оказалась актуальной и востребованной. И в один из вечеров вам на почтовый ящик пришло письмо, в котором какая-то компания спросила у вас, есть ли API, через который будет возможно забирать от вас эту информацию. Само собой, было предложено вознаграждение, которое показалось вам привлекательным. И вот перед вами встала задача запрограммировать какой-то сервис. Первым, что нужно сделать, это ответить на простой вопрос: “Какие действия пользователь может совершать с вашим сервисом?”

Ответом на этот вопрос может быть следующее:

  • Получить информацию о событиях, которые могут быть в определенный промежуток времени (год, месяц, неделя, день)
  • Получить информацию о конкретном событии

Вроде бы немного. И ничего страшного. Всего-то нужно посмотреть на то, за какой период времени вам нужно посмотреть информацию, взять из базы то, что соответствует условиям и отдать клиенту. Ok, Вы это сделали.

Когда дело было сделано, вы связались с потенциальным клиентом и скказали, что у вас все готово для предоставления информации и вы готовы предоставить API.

Допустим, оно оказылось таким:

Запросы:

GET /events/2012/11/01
GET /event/123456

Ответы:

{
  "events":[
    "event":{
      "date":"2012-11-01",
      "id":1
    },
    "event":{
      "date":"2012-11-01",
      "id":2
    }
  ]
}

Не навреди! Или о версионности API #

Форматы данных #

  • xml
  • json
  • RSS
  • php
  • raw
  • csv
  • wddx

Авторизация и аунтификация #

Документирование #

Что? #

  • Запрос:
    • Формат
    • Структура
    • Пример
  • Возвращаемые данные:
    • Формат
    • Структура
    • Пример
    • Примеры overload

Что можно еще? #

  • Заголовки сообщений
  • Использование HTTP заголовков
  • Возможные ошибки
  • Состояния
  • flow
  • use case
  • Варианты overload

Протоколы #

REST vs SOAP. Что выбрать? #

Главные преимущества REST web services #

  • “Легкость” – нет громоздких xml
  • Результат понятен и легко воспринимается
  • Легок в построении, нет необходимости в специальных инструментах

Преимещуства SOAP #

  • Иногда легок в использовании ©
  • Жесткое подчинение стандарту

REST vs SOAP #

  • Development tools
  • API Flexibility & Simplicity
  • Bandwidth Usage
  • Security
  • REST ain’t Perfect
  • Type Handling
  • Client-side Complexity
  • Testing and Troubleshooting
  • Server-side Complexity
  • Caching

HTTP Headers #

HTTP Response Codes #

3 типа дизайна API #

  • only HTTP Headers
  • HTTP Headers + json body
  • Forget the http headers

Дружественный API #

  • pub / sub
  • customer requirements
  • self migration

На что стоит обратить внимание? #

  • Ваш API прост для использования? А для “попробовать”?
  • Может быть важе API должно быть RESTful?
  • Вам нужно много или мало данных?
  • Вы хотите контроллировать API траффик?
  • Вы планируете масштабировать API?
  • API должно быть понятно для потребителей услуг?
  • Как вы идентифицируете кто использует ваше API?
  • Какой тип аунтификации/авторизации вы используете?
  • Что насчет OAuth?
  • Какие новые угрозы безопасности могут существовать для API?

Инструментарий для тестирования и построения клиентов. #