Download - ITmozg, Даниил Павлючков
1
REST: от GET до HMAC или как создать
качественное REST API
Даниил Павлючков2012г.
2 Наши программы
3 Как им общаться между собой?
???
4 API – это …
API - application programming interface
Интерфейс для коммуникации между ПО.
API состоит из набора классов, процедур, функций, структур, абстрактного от внутренней логики приложения.
Почему API – это хорошо5
• Все сторонние приложения будут работать одинаково хорошо
• Пишется программистом для программиста
• Не нужно выставлять наружу бизнес-логику приложения
Примеры API6
• DirectX• OpenGL• Windows API• Linux Kernel API• Facebook API• Gtk, qt, X11…
“Как я объяснил REST своей жене”
7
http://tomayko.com/writings/rest-to-my-wife
REST (Representational State Transfer) – это подход к созданию архитектуры сетевых протоколов. Этот подход был описан в 2000г Ройем Филдингом, в своей докторской диссертации.
Что же такое REST?8
Рой Филдинг – идейный авторпротокола HTTP и соавтор веб-сервера Apache.
Рой Филдинг9
• Легкая масштабируемость• Общность интерфейсов• Независимое развертывание компонентов• Возможность внедрения посредников
Цели REST10
• Клиент-серверная архитектура• Stateless• Кешируемость• Многослойность• Общий интерфейс
Правила REST11
• Клиенты не задумываются о схеме БД• Серверы не задумываются о UI• Клиенты и серверы могут разрабатываться независимо
Клиент-сервернаяархитектура
12
• Информация о клиенте не хранится на сервере• Каждый запрос клиента содержит всю необходимую информацию для обработки на сервере
Stateless13
Запросы должны явно объявлять себя как кешируемые или нет. Клиент самостоятельно решает, кешировать такой запрос или нет.
Кешируемость14
• Возможно использование посредников, серверов-балансировщиков и кеш-хранилищей
• Клиент не должен знать, подсоединен он сейчас напрямую к серверу или работает с посредником
Многослойность15
Идентичный интерфейс между всеми серверами и всеми клиентами позволяет добиться слабого связывания и хорошего масштабирования.
Общий интерфейс16
Клиент может управлять состоянием ресурсов, через стандартные интерфейсы, при помощи глаголов.
Главный принцип REST17
Ресурс – уникальный объект, доступный по уникальному URL
Глагол – http метод (GET, POST, PUT, DELETE …)
REST over HTTP18
Пример RESTful API19
http://api.com/books http://api.com/books/id17
GET Вывести список URL всех книг Вывести информацию о конкретной книге
POST Добавить одну новую книгу Добавить новый ресурс в конкретную книгу
PUT Заменить все книги новыми Заменить конкретную книгу новой книгой
DELETE Удалить все книги Удалить конкретную книгу
Хорошее API – какое оно?20
???
Что отличает первоклассное API от хорошего API
21
• API легко использовать• API сложно сломать
• Внимание к деталям• Любовь к клиентам
Ключевые моменты22
Их слишком много, давайте по порядку.
Не отвечайте в HTML!23
Всегда отдавайте ответы на машинном языке,XML, JSON, CSV …
Используйте HTTP коды ошибок
24
Если что-то пошло не так, код ошибки долженобъяснять, какая именно часть запроса неработает.
Код ошибки должен быть дополнен уникальным текстовым описанием ошибки.
Различайте 4хх и 5хх ошибки
25
4хх – группа ошибок со стороны клиента. Это значит, что клиент может самостоятельно их исправить без вашей помощи.
5хх – группа ошибок со стороны сервера. Это значит, что клиент может открыть support-ticket, и спустя какое-то время его запрос будет обработан корректно.
Документируйте свое API26
Несколько часов, потраченные на написание документации, сэкономят вам дни ответов на вопросы клиентов.
Поддерживайте и XML, и JSON
27
Помните, что различные языки программирования и различные платформы предпочитают разные форматы данных.
Написать алгоритм конвертации array -> json и array -> xml на сервере займет всего 1-2 дня даже у junior developer.
Будьте аккуратны с oAuth28
Используйте oAuth только, если вы работаете с аналогом реального пользователя в вашем API.
Не заставляйте пользователей генерировать ссылки на запросы
29
Если вас спрашивают GET “product list”, то верните следующую структуру
<products><product id=“1”>http://api.com/products/id1</product><product id=“2”>http://api.com/products/id2</product>
</products>
Запросы должны возвращать ограниченное кол-во данных
30
Если вы спрашиваете GET “product list”, то сервер должен вернуть первые n продуктов.
Сервер также должен вернуть готовые ссылки для next page и prev page
Поддерживайте старые версии своего API
31
Если вы сделали крупное изменение в своем API, выложите его под новой ссылкой • http://api.com/v1/products• http://api.com/v2/products
REST API + security = ??32
Как можно защитить запрос
33
• HTTPS• Basic авторизация• oAuth• Подписать меткой
Алгоритм подписи запросов
34
Для подписи запроса необходима пара user + secret.
Подпись отправляется вместе с запросом, и позволяет проверить как авторство запроса, так и целостность данных.
Что подписывать?35
• Глагол• Ресурс• Дополнительные параметры
Как подписывать?36
Запрос нужно подписывать алгоритмом, который поддерживает подпись на основе секретного ключа.
Для этого идеально подходитHMAC – hash-based message authentication code.
Алгоритм HMAC37
Подписываю!38
Запросhttp://api.com/photos/id547
ЗаголовкиGET /photos/id547 HTTP/1.1Host: api.comDate: Thu, 16 May 2012 19:37:58 +0000
Алгоритм создания подписи
39
1. Начинаем с пустой строки2. Добавляем глагол запроса (GET, POST, PUT, DELETE)3. Добавляем перенос строки \n4. Добавляем точку входа (например, photos/id547)5. Добавляем перенос строки \n6. Добавляем канонизированную строку с параметрами запроса
1. Сортируем все параметры по ключу в натуральном порядке2. urlencode ключ и значение параметра3. Добавляем параметры в одну строку в формате
key1=value1&key2=value2&key3=value3...7. Полученную строку кодируем при помощи hmac с секретом
юзера.8. Кодируем цифровую подпись при помощи base64
Формируем запрос40
Запрос http://api.com/photos/id547
Реальный запрос http://api.com/photos/id547?api_user=john
Подписываем запрос41
http://api.com/photos/id547?api_user=john
Строка для подписи GET\nphotos/id547\napi_user=john
Подпись - xXjDGYUmKxnwqr5KXNPGldn5LbA=
Отправляем запрос42
http://api.com/photos/id547?api_user=john
Подпись xXjDGYUmKxnwqr5KXNPGldn5LbA=
Финальный запросhttp://api.com/photos/id547?api_user=john&signature= xXjDGYUmKxnwqr5KXNPGldn5LbA=
Что делает сервер?43
• Находит secret в БД по имени пользователя • Создает собственный версию подписи• Сравнивает пришедшую подпись с только что созданной
Что еще можно добавить в подпись?
44
• Тип данных• md5 чексумма данных• Время отправки запросов• Дополнительные HTTP заголовки
В заключение45
API – точно такая же часть вашего приложения, как и хранение данных или его бизнес-логика.
Проектируйте API по тем же самым процессам (TDD, MVC …), что и остальные части вашего ПО.