1
2
Разработка RESTful API
with all the bells and
whistles
Роман Акинфеев
3
Яндекс.Диск — это сервис, который позволяет
хранить файлы и обмениваться ими, а также
предоставляет доступ к файлам с лю...
4
Яндекс.Диск — это сервис, который позволяет
хранить файлы и обмениваться ими, а также
предоставляет доступ к файлам с лю...
5
Яндекс.Диск — это сервис, который позволяет
хранить файлы и обмениваться ими, а также
предоставляет доступ к файлам с лю...
6
Яндекс.Диск — это сервис, который позволяет
хранить файлы и обмениваться ими, а также
предоставляет доступ к файлам с лю...
7
Yandex Disk APIs
WebDAV
Для работы с Диском, как с файловой системой
RESTful API
Для работы с Диском там, где WebDAV’а м...
8
Yandex Disk APIs
WebDAV
Для работы с Диском, как с файловой системой
RESTful API
Для работы с Диском там, где WebDAV’а м...
9
Задачи
10
Задачи
• Простота изучения возможностей API
Легко расширяемая функциональность
Простота разработки под API
11
Задачи
• Простота изучения возможностей API
• Легко расширяемая функциональность
Простота разработки под API
12
Задачи
• Простота изучения возможностей API
• Легко расширяемая функциональность
• Простота разработки под API
13
RESTful API Яндекс Диска
• Понятная и логичная структура
Hypermedia API
Self-descriptive & Machine-readable API
14
RESTful API Яндекс Диска
• Понятная и логичная структура
• Hypermedia API
Self-descriptive & Machine-readable API
15
RESTful API Яндекс Диска
• Понятная и логичная структура
• Hypermedia API
• Self-descriptive & Machine-readable API
16
Что такое REST?
• Просто набор принципов
• Никаких готовых решений
• Только ограничения
17
Клиент-сервер и интерфейс
• Клиент и сервер знают
интерфейс
• Клиент и сервер не знают
друг друга
Профит
Много клиентов...
18
Клиент-сервер и интерфейс
• Клиент и сервер знают
интерфейс
• Клиент и сервер не знают
друг друга
Профит
• Много клиент...
19
Stateless
• Сервер не хранит никакой информации о состоянии
клиента между запросами
Нет соединений
Нет сессий
Нет истор...
20
Stateless
• Сервер не хранит никакой информации о состоянии
клиента между запросами
• Нет соединений
• Нет сессий
• Нет...
21
Stateless
• Сервер не хранит никакой информации о состоянии
клиента между запросами
• Нет соединений
• Нет сессий
• Нет...
22
Кэшируемость и многослойность
• Сервер сообщает, что и как кэшировать
• Клиент может не соединяться напрямую с сервером...
23
Кэшируемость и многослойность
• Сервер сообщает, что и как кэшировать
• Клиент может не соединяться напрямую с сервером...
24
Рецепт
RESTful API Яндекс Диска
25
Ресурсы
26
Ресурсы
• Система оперирует ресурсами
Ресурсы имеют чёткую структуру
URL – уникальный идентификатор ресурса
Ресурсы API...
27
Ресурсы
• Система оперирует ресурсами
• Ресурсы имеют чёткую структуру
URL – уникальный идентификатор ресурса
Ресурсы A...
28
Ресурсы
• Система оперирует ресурсами
• Ресурсы имеют чёткую структуру
• URL – уникальный идентификатор ресурса
Ресурсы...
29
Ресурсы
• Система оперирует ресурсами
• Ресурсы имеют чёткую структуру
• URL – уникальный идентификатор ресурса
Ресурсы...
30
URL ресурсов
31
URL ресурсов
URL группируются в нэймспэйсы
/disk
URL коллекции ресурсов всегда во множественном числе
/disk / resources...
32
URL ресурсов
URL группируются в нэймспэйсы
/disk
URL коллекции ресурсов всегда во множественном числе
/disk / resources...
33
URL ресурсов
URL группируются в нэймспэйсы
/disk
URL коллекции ресурсов всегда во множественном числе
/disk / resources...
34
URL ресурсов
URL группируются в нэймспэйсы
/disk
URL коллекции ресурсов всегда во множественном числе
/disk / resources...
35
HTTP-методы
Основные CRUD-операции:
GET, POST, PUT, DELETE
36
HTTP-методы
GET – безопасный. Делаем запрос, не задумываясь:
GET /disk/resources?path={path}
GET /disk/operations?id={i...
37
HTTP-методы
GET – безопасный. Делаем запрос, не задумываясь:
GET /disk/resources?path={path}
GET /disk/operations?id={i...
38
HTTP-методы
GET – безопасный. Делаем запрос, не задумываясь:
GET /disk/resources?path={path}
GET /disk/operations?id={i...
39
HTTP-методы
GET – безопасный. Делаем запрос, не задумываясь:
GET /disk/resources?path={path}
GET /disk/operations?id={i...
40
Когда CRUD мало
41
Когда CRUD мало
Копирование и Перемещение
• Не идемпотентны
• Не безопасны
Надо использовать POST, но метод один, а опе...
42
Когда CRUD мало
Копирование и Перемещение
• Не идемпотентны
• Не безопасны
Надо использовать POST, но метод один, а опе...
43
Когда CRUD мало
Копирование и Перемещение
• Не идемпотентны
• Не безопасны
Надо использовать POST, но метод один, а опе...
44
The Bells And Whistles
RESTful API Яндекс Диска
45
Hypermedia API
Предоставлять данные о том, что можно делать с каждым ресурсом.
Hypermedia as the Engine of Application ...
46
Hypermedia API
Предоставлять данные о том, что можно делать с каждым ресурсом.
Hypermedia as the Engine of Application ...
47
Hypermedia API
Предоставлять данные о том, что можно делать с каждым ресурсом.
Hypermedia as the Engine of Application ...
48
Hypermedia API
• Collection+JSON
• HAL
• DocJSON
• JSON API
• JSON Hyperschema
49
Hypertext Application Language
• Чрезвычайно прост
• Есть draft RFC-стандарта
• Уже встречается в публичных API
• MIME-...
50
Hypertext Application Language
• Чрезвычайно прост
• Есть draft RFC-стандарта
• Уже встречается в публичных API
• MIME-...
51
Обычное API
# пусть у нас есть объект папки
print folder
{
“name”: “foo”,
“path”: “disk:/foo”,
“type”: “dir”
}
# удаляе...
52
Hypermedia API
# пусть у нас есть объект папки с HAL-ссылками
print folder
{
"_links": {
"delete": {
"href": "https://c...
53
Self-describing & Machine-readable
Машиночитаемые способы описания REST API
• RAML
• WADL
• JSON Schema + JSON HyperSch...
54
Swagger
• Описывает API в виде JSON
• Развивается как стандарт
• Прост для понимания
• Имеет экосистему инструментов
55
Swagger описывает
• Структуру API
• Параметры операций над ресурсами
• Структуру возвращаемых объектов
56
Профит от Swagger
• Универсальные Swagger-клиенты
• Автогенерация частей нативных SDK
• Готовый open source UI для API
57
tech.yandex.ru/disk/poligon
58
Что в итоге получилось
59
Что в итоге получилось
• Понятная и расширяемая структура
Удобная навигация по API с помощью ссылок
Самодокументируемос...
60
Что в итоге получилось
• Понятная и расширяемая структура
• Удобная навигация по API с помощью ссылок
Самодокументируем...
61
Что в итоге получилось
• Понятная и расширяемая структура
• Удобная навигация по API с помощью ссылок
• Самодокументиру...
62
Рецепт правильного REST API
63
Рецепт правильного REST API
• Структура в виде ресурсов и операций над ними
Доступ к объектам через коллекции
Старайтес...
64
Рецепт правильного REST API
• Структура в виде ресурсов и операций над ними
• Доступ к объектам через коллекции
Старайт...
65
Рецепт правильного REST API
• Структура в виде ресурсов и операций над ними
• Доступ к объектам через коллекции
• Стара...
66
Рецепт правильного REST API
• Структура в виде ресурсов и операций над ними
• Доступ к объектам через коллекции
• Стара...
67
Рецепт правильного REST API
• Структура в виде ресурсов и операций над ними
• Доступ к объектам через коллекции
• Стара...
68
Рецепт правильного REST API
• Структура в виде ресурсов и операций над ними
• Доступ к объектам через коллекции
• Стара...
69
Для чего использовать API Диска
• Работа с контентом пользователей
• Синхронизация данных между устройствами
• Хранение...
70
Спасибо за внимание!
71
Роман Акинфеев
Разработчик back-end и REST API Яндекс.Диска
Клуб разработчиков:
Сервис «Полигон»: tech.yandex.ru/disk/p...
Upcoming SlideShare
Loading in …5
×

Разработка RESTful api with all bells and whistles

5,157 views

Published on

Published in: Technology
  • Be the first to comment

Разработка RESTful api with all bells and whistles

  1. 1. 1
  2. 2. 2 Разработка RESTful API with all the bells and whistles Роман Акинфеев
  3. 3. 3 Яндекс.Диск — это сервис, который позволяет хранить файлы и обмениваться ими, а также предоставляет доступ к файлам с любого устройства, подключённого к интернету. • 20+ млн. зарегистрированных пользователей • 10+ млн. загружаемых в сутки файлов • 7+ млрд. файлов
  4. 4. 4 Яндекс.Диск — это сервис, который позволяет хранить файлы и обмениваться ими, а также предоставляет доступ к файлам с любого устройства, подключённого к интернету. • 20+ млн. зарегистрированных пользователей 10+ млн. загружаемых в сутки файлов 7+ млрд. файлов
  5. 5. 5 Яндекс.Диск — это сервис, который позволяет хранить файлы и обмениваться ими, а также предоставляет доступ к файлам с любого устройства, подключённого к интернету. • 20+ млн. зарегистрированных пользователей • 10+ млн. загружаемых в сутки файлов 7+ млрд. файлов
  6. 6. 6 Яндекс.Диск — это сервис, который позволяет хранить файлы и обмениваться ими, а также предоставляет доступ к файлам с любого устройства, подключённого к интернету. • 20+ млн. зарегистрированных пользователей • 10+ млн. загружаемых в сутки файлов • 7+ млрд. файлов
  7. 7. 7 Yandex Disk APIs WebDAV Для работы с Диском, как с файловой системой RESTful API Для работы с Диском там, где WebDAV’а мало
  8. 8. 8 Yandex Disk APIs WebDAV Для работы с Диском, как с файловой системой RESTful API Для работы с Диском там, где WebDAV’а мало
  9. 9. 9 Задачи
  10. 10. 10 Задачи • Простота изучения возможностей API Легко расширяемая функциональность Простота разработки под API
  11. 11. 11 Задачи • Простота изучения возможностей API • Легко расширяемая функциональность Простота разработки под API
  12. 12. 12 Задачи • Простота изучения возможностей API • Легко расширяемая функциональность • Простота разработки под API
  13. 13. 13 RESTful API Яндекс Диска • Понятная и логичная структура Hypermedia API Self-descriptive & Machine-readable API
  14. 14. 14 RESTful API Яндекс Диска • Понятная и логичная структура • Hypermedia API Self-descriptive & Machine-readable API
  15. 15. 15 RESTful API Яндекс Диска • Понятная и логичная структура • Hypermedia API • Self-descriptive & Machine-readable API
  16. 16. 16 Что такое REST? • Просто набор принципов • Никаких готовых решений • Только ограничения
  17. 17. 17 Клиент-сервер и интерфейс • Клиент и сервер знают интерфейс • Клиент и сервер не знают друг друга Профит Много клиентов хороших и разных Сервер не замечает, как обновляются клиенты Клиенты не замечают, как обновляется сервер
  18. 18. 18 Клиент-сервер и интерфейс • Клиент и сервер знают интерфейс • Клиент и сервер не знают друг друга Профит • Много клиентов хороших и разных • Сервер не замечает, как обновляются клиенты • Клиенты не замечают, как обновляется сервер
  19. 19. 19 Stateless • Сервер не хранит никакой информации о состоянии клиента между запросами Нет соединений Нет сессий Нет истории операций клиента Профит Бэкэнд легко масштабируется Клиент не беспокоится ни о чём между запросами
  20. 20. 20 Stateless • Сервер не хранит никакой информации о состоянии клиента между запросами • Нет соединений • Нет сессий • Нет истории операций клиента Профит Бэкэнд легко масштабируется Клиент не беспокоится ни о чём между запросами
  21. 21. 21 Stateless • Сервер не хранит никакой информации о состоянии клиента между запросами • Нет соединений • Нет сессий • Нет истории операций клиента Профит • Бэкэнд легко масштабируется • Клиент не беспокоится ни о чём между запросами
  22. 22. 22 Кэшируемость и многослойность • Сервер сообщает, что и как кэшировать • Клиент может не соединяться напрямую с сервером Профит Возможность снизить нагрузку на бэкэнд Возможность работать с кэшем на клиенте
  23. 23. 23 Кэшируемость и многослойность • Сервер сообщает, что и как кэшировать • Клиент может не соединяться напрямую с сервером Профит • Возможность снизить нагрузку на бэкэнд • Возможность работать с кэшем на клиенте
  24. 24. 24 Рецепт RESTful API Яндекс Диска
  25. 25. 25 Ресурсы
  26. 26. 26 Ресурсы • Система оперирует ресурсами Ресурсы имеют чёткую структуру URL – уникальный идентификатор ресурса Ресурсы API Диска: Файлы и папки – resources Асинхронные операции – operations
  27. 27. 27 Ресурсы • Система оперирует ресурсами • Ресурсы имеют чёткую структуру URL – уникальный идентификатор ресурса Ресурсы API Диска: Файлы и папки – resources Асинхронные операции – operations
  28. 28. 28 Ресурсы • Система оперирует ресурсами • Ресурсы имеют чёткую структуру • URL – уникальный идентификатор ресурса Ресурсы API Диска: Файлы и папки – resources Асинхронные операции – operations
  29. 29. 29 Ресурсы • Система оперирует ресурсами • Ресурсы имеют чёткую структуру • URL – уникальный идентификатор ресурса Ресурсы API Диска: • Файлы и папки – resources • Асинхронные операции – operations
  30. 30. 30 URL ресурсов
  31. 31. 31 URL ресурсов URL группируются в нэймспэйсы /disk URL коллекции ресурсов всегда во множественном числе /disk / resources /disk / operations URL коллекции + идентификатор = URL ресурса /disk / resources ? path={path} /disk / operations ? id={id} /pets / kittens / {name}
  32. 32. 32 URL ресурсов URL группируются в нэймспэйсы /disk URL коллекции ресурсов всегда во множественном числе /disk / resources /disk / operations URL коллекции + идентификатор = URL ресурса /disk / resources ? path={path} /disk / operations ? id={id} /pets / kittens / {name}
  33. 33. 33 URL ресурсов URL группируются в нэймспэйсы /disk URL коллекции ресурсов всегда во множественном числе /disk / resources /disk / operations URL коллекции + идентификатор = URL ресурса /disk / resources ? path={path} /disk / operations ? id={id} /pets / kittens / {name}
  34. 34. 34 URL ресурсов URL группируются в нэймспэйсы /disk URL коллекции ресурсов всегда во множественном числе /disk / resources /disk / operations URL коллекции + идентификатор = URL ресурса /disk / resources ? path={path} /disk / operations ? id={id} /pets / kittens / {name}
  35. 35. 35 HTTP-методы Основные CRUD-операции: GET, POST, PUT, DELETE
  36. 36. 36 HTTP-методы GET – безопасный. Делаем запрос, не задумываясь: GET /disk/resources?path={path} GET /disk/operations?id={id} GET, PUT, DELETE – идемпотентные. Повторяем при обрыве, не задумываясь: PUT /disk/resources?path={path} DELETE /disk/resources?path={path} POST – опасный. Изменяет состояние ресурса, повторять опасно OPTIONS – подскажет поддерживаемые ресурсом методы
  37. 37. 37 HTTP-методы GET – безопасный. Делаем запрос, не задумываясь: GET /disk/resources?path={path} GET /disk/operations?id={id} GET, PUT, DELETE – идемпотентные. Повторяем при обрыве, не задумываясь: PUT /disk/resources?path={path} DELETE /disk/resources?path={path} POST – опасный. Изменяет состояние ресурса, повторять опасно OPTIONS – подскажет поддерживаемые ресурсом методы
  38. 38. 38 HTTP-методы GET – безопасный. Делаем запрос, не задумываясь: GET /disk/resources?path={path} GET /disk/operations?id={id} GET, PUT, DELETE – идемпотентные. Повторяем при обрыве, не задумываясь: PUT /disk/resources?path={path} DELETE /disk/resources?path={path} POST – опасный. Изменяет состояние ресурса, повторять опасно OPTIONS – подскажет поддерживаемые ресурсом методы
  39. 39. 39 HTTP-методы GET – безопасный. Делаем запрос, не задумываясь: GET /disk/resources?path={path} GET /disk/operations?id={id} GET, PUT, DELETE – идемпотентные. Повторяем при обрыве, не задумываясь: PUT /disk/resources?path={path} DELETE /disk/resources?path={path} POST – опасный. Изменяет состояние ресурса, повторять опасно OPTIONS – подскажет поддерживаемые ресурсом методы
  40. 40. 40 Когда CRUD мало
  41. 41. 41 Когда CRUD мало Копирование и Перемещение • Не идемпотентны • Не безопасны Надо использовать POST, но метод один, а операции две На помощь приходят они! Ad Hoc-методы! POST /disk/resources/ copy ? path={path}&from={from} POST /disk/resources/ move ? path={path}&from={from}
  42. 42. 42 Когда CRUD мало Копирование и Перемещение • Не идемпотентны • Не безопасны Надо использовать POST, но метод один, а операции две На помощь приходят они! Ad Hoc-методы! POST /disk/resources/ copy ? path={path}&from={from} POST /disk/resources/ move ? path={path}&from={from}
  43. 43. 43 Когда CRUD мало Копирование и Перемещение • Не идемпотентны • Не безопасны Надо использовать POST, но метод один, а операции две На помощь приходят они! Ad Hoc-методы! POST /disk/resources/ copy ? path={path}&from={from} POST /disk/resources/ move ? path={path}&from={from}
  44. 44. 44 The Bells And Whistles RESTful API Яндекс Диска
  45. 45. 45 Hypermedia API Предоставлять данные о том, что можно делать с каждым ресурсом. Hypermedia as the Engine of Application State Клиент должен взаимодействовать с сервером посредством hypermedia-контролов, получаемых от сервера. Профит Клиент не дёргает захардкоденные URL Клиент переходит по ссылкам
  46. 46. 46 Hypermedia API Предоставлять данные о том, что можно делать с каждым ресурсом. Hypermedia as the Engine of Application State Клиент должен взаимодействовать с сервером посредством hypermedia-контролов, получаемых от сервера. Профит Клиент не дёргает захардкоденные URL Клиент переходит по ссылкам
  47. 47. 47 Hypermedia API Предоставлять данные о том, что можно делать с каждым ресурсом. Hypermedia as the Engine of Application State Клиент должен взаимодействовать с сервером посредством hypermedia-контролов, получаемых от сервера. Профит • Клиент не дёргает захардкоденные URL • Клиент переходит по ссылкам
  48. 48. 48 Hypermedia API • Collection+JSON • HAL • DocJSON • JSON API • JSON Hyperschema
  49. 49. 49 Hypertext Application Language • Чрезвычайно прост • Есть draft RFC-стандарта • Уже встречается в публичных API • MIME-type: application/hal+json Благодаря HAL Клиент знает, что и как может сделать с объектом Сервер может управлять набором доступных действий
  50. 50. 50 Hypertext Application Language • Чрезвычайно прост • Есть draft RFC-стандарта • Уже встречается в публичных API • MIME-type: application/hal+json Благодаря HAL • Клиент знает, что и как может сделать с объектом • Сервер может управлять набором доступных действий
  51. 51. 51 Обычное API # пусть у нас есть объект папки print folder { “name”: “foo”, “path”: “disk:/foo”, “type”: “dir” } # удаляем папку URL = 'https://cloud-api.yandex.net/v1/disk/resources' query = {} query['path'] = folder['path'] query['permanently'] = True qs = urlencode(query) url = URL + '?' + qs request('DELETE', url) <Response [204]>
  52. 52. 52 Hypermedia API # пусть у нас есть объект папки с HAL-ссылками print folder { "_links": { "delete": { "href": "https://cloud- api.yandex.net/v1/disk/resources?path=disk%3A%2Ffoo&permanently=True", "method": "DELETE" }, }, “name”: “foo”, “path”: “disk:/foo”, “type”: “dir” } # удаляем папку action = folder[‘_links’][‘delete’] request(action[‘method’], action[‘href’]) <Response [204]>
  53. 53. 53 Self-describing & Machine-readable Машиночитаемые способы описания REST API • RAML • WADL • JSON Schema + JSON HyperSchema • Swagger • IO Docs • Apiary Blueprints
  54. 54. 54 Swagger • Описывает API в виде JSON • Развивается как стандарт • Прост для понимания • Имеет экосистему инструментов
  55. 55. 55 Swagger описывает • Структуру API • Параметры операций над ресурсами • Структуру возвращаемых объектов
  56. 56. 56 Профит от Swagger • Универсальные Swagger-клиенты • Автогенерация частей нативных SDK • Готовый open source UI для API
  57. 57. 57 tech.yandex.ru/disk/poligon
  58. 58. 58 Что в итоге получилось
  59. 59. 59 Что в итоге получилось • Понятная и расширяемая структура Удобная навигация по API с помощью ссылок Самодокументируемость и машиночитаемость
  60. 60. 60 Что в итоге получилось • Понятная и расширяемая структура • Удобная навигация по API с помощью ссылок Самодокументируемость и машиночитаемость
  61. 61. 61 Что в итоге получилось • Понятная и расширяемая структура • Удобная навигация по API с помощью ссылок • Самодокументируемость и машиночитаемость
  62. 62. 62 Рецепт правильного REST API
  63. 63. 63 Рецепт правильного REST API • Структура в виде ресурсов и операций над ними Доступ к объектам через коллекции Старайтесь придерживаться RFC 2616 Используйте Ad Hoc-методы там где не хватает HTTP Добавляйте в API hypermedia-контролы HAL – http://stateless.co/hal_specification.html Описывайте API с помощью машиночитаемых форматов Swagger – https://helloreverb.com/developers/swagger
  64. 64. 64 Рецепт правильного REST API • Структура в виде ресурсов и операций над ними • Доступ к объектам через коллекции Старайтесь придерживаться RFC 2616 Используйте Ad Hoc-методы там где не хватает HTTP Добавляйте в API hypermedia-контролы HAL – http://stateless.co/hal_specification.html Описывайте API с помощью машиночитаемых форматов Swagger – https://helloreverb.com/developers/swagger
  65. 65. 65 Рецепт правильного REST API • Структура в виде ресурсов и операций над ними • Доступ к объектам через коллекции • Старайтесь придерживаться RFC 2616 Используйте Ad Hoc-методы там где не хватает HTTP Добавляйте в API hypermedia-контролы HAL – http://stateless.co/hal_specification.html Описывайте API с помощью машиночитаемых форматов Swagger – https://helloreverb.com/developers/swagger
  66. 66. 66 Рецепт правильного REST API • Структура в виде ресурсов и операций над ними • Доступ к объектам через коллекции • Старайтесь придерживаться RFC 2616 • Используйте Ad Hoc-методы там где не хватает HTTP Добавляйте в API hypermedia-контролы HAL – http://stateless.co/hal_specification.html Описывайте API с помощью машиночитаемых форматов Swagger – https://helloreverb.com/developers/swagger
  67. 67. 67 Рецепт правильного REST API • Структура в виде ресурсов и операций над ними • Доступ к объектам через коллекции • Старайтесь придерживаться RFC 2616 • Используйте Ad Hoc-методы там где не хватает HTTP • Добавляйте в API hypermedia-контролы HAL – http://stateless.co/hal_specification.html Описывайте API с помощью машиночитаемых форматов Swagger – https://helloreverb.com/developers/swagger
  68. 68. 68 Рецепт правильного REST API • Структура в виде ресурсов и операций над ними • Доступ к объектам через коллекции • Старайтесь придерживаться RFC 2616 • Используйте Ad Hoc-методы там где не хватает HTTP • Добавляйте в API hypermedia-контролы HAL – http://stateless.co/hal_specification.html • Описывайте API с помощью машиночитаемых форматов Swagger – https://helloreverb.com/developers/swagger
  69. 69. 69 Для чего использовать API Диска • Работа с контентом пользователей • Синхронизация данных между устройствами • Хранение user-related данных приложений
  70. 70. 70 Спасибо за внимание!
  71. 71. 71 Роман Акинфеев Разработчик back-end и REST API Яндекс.Диска Клуб разработчиков: Сервис «Полигон»: tech.yandex.ru/disk/poligon clubs.ya.ru/apidisk/

×