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 …), что и остальные части вашего ПО.

46

ПавлючковДаниил

d.pavluchkov@itmozg.ru

Вопросы?