Каждый уважающий себя интернет-сервис, ориентированный больше чем на одну платформу, сегодня имеет RESTful API. Но мало кто понимает что такое REST, с чем его едят, как готовят и чем он полезен для здоровья. Кто-то считает, что RESTful API - это API использующее в качестве транспорта протокол HTTP, кто-то думает, что REST - это стандарт в рамках которого разработчики ограничены набором ресурсов и восьмью операциями над ними. Я расскажу о том как мы в Яндекс.Диске понимаем REST, как его готовим и какую пользу он нам приносит.

1. 1

2. 2
Разработка RESTful API
with all the bells and
whistles
Роман Акинфеев

3. 3
Яндекс.Диск — это сервис, который позволяет
хранить файлы и обмениваться ими, а также
предоставляет доступ к файлам с любого
устройства, подключённого к интернету.
• 20+ млн. зарегистрированных пользователей
• 10+ млн. загружаемых в сутки файлов
• 7+ млрд. файлов

4. 4
Яндекс.Диск — это сервис, который позволяет
хранить файлы и обмениваться ими, а также
предоставляет доступ к файлам с любого
устройства, подключённого к интернету.
• 20+ млн. зарегистрированных пользователей
10+ млн. загружаемых в сутки файлов
7+ млрд. файлов

5. 5
Яндекс.Диск — это сервис, который позволяет
хранить файлы и обмениваться ими, а также
предоставляет доступ к файлам с любого
устройства, подключённого к интернету.
• 20+ млн. зарегистрированных пользователей
• 10+ млн. загружаемых в сутки файлов
7+ млрд. файлов

6. 6
Яндекс.Диск — это сервис, который позволяет
хранить файлы и обмениваться ими, а также
предоставляет доступ к файлам с любого
устройства, подключённого к интернету.
• 20+ млн. зарегистрированных пользователей
• 10+ млн. загружаемых в сутки файлов
• 7+ млрд. файлов

7. 7
Yandex Disk APIs
WebDAV
Для работы с Диском, как с файловой системой
RESTful API
Для работы с Диском там, где WebDAV’а мало

8. 8
Yandex Disk APIs
WebDAV
Для работы с Диском, как с файловой системой
RESTful API
Для работы с Диском там, где WebDAV’а мало

9. 9
Задачи

10. 10
Задачи
• Простота изучения возможностей API
Легко расширяемая функциональность
Простота разработки под API

11. 11
Задачи
• Простота изучения возможностей API
• Легко расширяемая функциональность
Простота разработки под API

12. 12
Задачи
• Простота изучения возможностей API
• Легко расширяемая функциональность
• Простота разработки под API

13. 13
RESTful API Яндекс Диска
• Понятная и логичная структура
Hypermedia API
Self-descriptive & Machine-readable API

14. 14
RESTful API Яндекс Диска
• Понятная и логичная структура
• Hypermedia API
Self-descriptive & Machine-readable API

15. 15
RESTful API Яндекс Диска
• Понятная и логичная структура
• Hypermedia API
• Self-descriptive & Machine-readable API

16. 16
Что такое REST?
• Просто набор принципов
• Никаких готовых решений
• Только ограничения

17. 17
Клиент-сервер и интерфейс
• Клиент и сервер знают
интерфейс
• Клиент и сервер не знают
друг друга
Профит
Много клиентов хороших и
разных
Сервер не замечает, как
обновляются клиенты
Клиенты не замечают, как
обновляется сервер

18. 18
Клиент-сервер и интерфейс
• Клиент и сервер знают
интерфейс
• Клиент и сервер не знают
друг друга
Профит
• Много клиентов хороших и
разных
• Сервер не замечает, как
обновляются клиенты
• Клиенты не замечают, как
обновляется сервер

19. 19
Stateless
• Сервер не хранит никакой информации о состоянии
клиента между запросами
Нет соединений
Нет сессий
Нет истории операций клиента
Профит
Бэкэнд легко масштабируется
Клиент не беспокоится ни о чём между запросами

20. 20
Stateless
• Сервер не хранит никакой информации о состоянии
клиента между запросами
• Нет соединений
• Нет сессий
• Нет истории операций клиента
Профит
Бэкэнд легко масштабируется
Клиент не беспокоится ни о чём между запросами

21. 21
Stateless
• Сервер не хранит никакой информации о состоянии
клиента между запросами
• Нет соединений
• Нет сессий
• Нет истории операций клиента
Профит
• Бэкэнд легко масштабируется
• Клиент не беспокоится ни о чём между запросами

22. 22
Кэшируемость и многослойность
• Сервер сообщает, что и как кэшировать
• Клиент может не соединяться напрямую с сервером
Профит
Возможность снизить нагрузку на бэкэнд
Возможность работать с кэшем на клиенте

23. 23
Кэшируемость и многослойность
• Сервер сообщает, что и как кэшировать
• Клиент может не соединяться напрямую с сервером
Профит
• Возможность снизить нагрузку на бэкэнд
• Возможность работать с кэшем на клиенте

24. 24
Рецепт
RESTful API Яндекс Диска

25. 25
Ресурсы

26. 26
Ресурсы
• Система оперирует ресурсами
Ресурсы имеют чёткую структуру
URL – уникальный идентификатор ресурса
Ресурсы API Диска:
Файлы и папки – resources
Асинхронные операции – operations

27. 27
Ресурсы
• Система оперирует ресурсами
• Ресурсы имеют чёткую структуру
URL – уникальный идентификатор ресурса
Ресурсы API Диска:
Файлы и папки – resources
Асинхронные операции – operations

28. 28
Ресурсы
• Система оперирует ресурсами
• Ресурсы имеют чёткую структуру
• URL – уникальный идентификатор ресурса
Ресурсы API Диска:
Файлы и папки – resources
Асинхронные операции – operations

29. 29
Ресурсы
• Система оперирует ресурсами
• Ресурсы имеют чёткую структуру
• URL – уникальный идентификатор ресурса
Ресурсы API Диска:
• Файлы и папки – resources
• Асинхронные операции – operations

30. 30
URL ресурсов

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
URL ресурсов
URL группируются в нэймспэйсы
/disk
URL коллекции ресурсов всегда во множественном числе
/disk / resources
/disk / operations
URL коллекции + идентификатор = URL ресурса
/disk / resources ? path={path}
/disk / operations ? id={id}
/pets / kittens / {name}

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
URL ресурсов
URL группируются в нэймспэйсы
/disk
URL коллекции ресурсов всегда во множественном числе
/disk / resources
/disk / operations
URL коллекции + идентификатор = URL ресурса
/disk / resources ? path={path}
/disk / operations ? id={id}
/pets / kittens / {name}

35. 35
HTTP-методы
Основные CRUD-операции:
GET, POST, PUT, DELETE

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
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
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
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
Когда CRUD мало

41. 41
Когда CRUD мало
Копирование и Перемещение
• Не идемпотентны
• Не безопасны
Надо использовать POST, но метод один, а операции две
На помощь приходят они! Ad Hoc-методы!
POST /disk/resources/ copy ? path={path}&from={from}
POST /disk/resources/ move ? path={path}&from={from}

42. 42
Когда CRUD мало
Копирование и Перемещение
• Не идемпотентны
• Не безопасны
Надо использовать POST, но метод один, а операции две
На помощь приходят они! Ad Hoc-методы!
POST /disk/resources/ copy ? path={path}&from={from}
POST /disk/resources/ move ? path={path}&from={from}

43. 43
Когда CRUD мало
Копирование и Перемещение
• Не идемпотентны
• Не безопасны
Надо использовать POST, но метод один, а операции две
На помощь приходят они! Ad Hoc-методы!
POST /disk/resources/ copy ? path={path}&from={from}
POST /disk/resources/ move ? path={path}&from={from}

44. 44
The Bells And Whistles
RESTful API Яндекс Диска

45. 45
Hypermedia API
Предоставлять данные о том, что можно делать с каждым ресурсом.
Hypermedia as the Engine of Application State
Клиент должен взаимодействовать с сервером посредством
hypermedia-контролов, получаемых от сервера.
Профит
Клиент не дёргает захардкоденные URL
Клиент переходит по ссылкам

46. 46
Hypermedia API
Предоставлять данные о том, что можно делать с каждым ресурсом.
Hypermedia as the Engine of Application State
Клиент должен взаимодействовать с сервером посредством
hypermedia-контролов, получаемых от сервера.
Профит
Клиент не дёргает захардкоденные URL
Клиент переходит по ссылкам

47. 47
Hypermedia API
Предоставлять данные о том, что можно делать с каждым ресурсом.
Hypermedia as the Engine of Application State
Клиент должен взаимодействовать с сервером посредством
hypermedia-контролов, получаемых от сервера.
Профит
• Клиент не дёргает захардкоденные URL
• Клиент переходит по ссылкам

48. 48
Hypermedia API
• Collection+JSON
• HAL
• DocJSON
• JSON API
• JSON Hyperschema

49. 49
Hypertext Application Language
• Чрезвычайно прост
• Есть draft RFC-стандарта
• Уже встречается в публичных API
• MIME-type: application/hal+json
Благодаря HAL
Клиент знает, что и как может сделать с объектом
Сервер может управлять набором доступных действий

50. 50
Hypertext Application Language
• Чрезвычайно прост
• Есть draft RFC-стандарта
• Уже встречается в публичных API
• MIME-type: application/hal+json
Благодаря HAL
• Клиент знает, что и как может сделать с объектом
• Сервер может управлять набором доступных действий

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
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
Self-describing & Machine-readable
Машиночитаемые способы описания REST API
• RAML
• WADL
• JSON Schema + JSON HyperSchema
• Swagger
• IO Docs
• Apiary Blueprints

54. 54
Swagger
• Описывает API в виде JSON
• Развивается как стандарт
• Прост для понимания
• Имеет экосистему инструментов

55. 55
Swagger описывает
• Структуру API
• Параметры операций над ресурсами
• Структуру возвращаемых объектов

56. 56
Профит от Swagger
• Универсальные Swagger-клиенты
• Автогенерация частей нативных SDK
• Готовый open source UI для API

57. 57
tech.yandex.ru/disk/poligon

58. 58
Что в итоге получилось

59. 59
Что в итоге получилось
• Понятная и расширяемая структура
Удобная навигация по API с помощью ссылок
Самодокументируемость и машиночитаемость

60. 60
Что в итоге получилось
• Понятная и расширяемая структура
• Удобная навигация по API с помощью ссылок
Самодокументируемость и машиночитаемость

61. 61
Что в итоге получилось
• Понятная и расширяемая структура
• Удобная навигация по API с помощью ссылок
• Самодокументируемость и машиночитаемость

62. 62
Рецепт правильного REST API

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
Рецепт правильного 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
Рецепт правильного 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
Рецепт правильного 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
Рецепт правильного 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
Рецепт правильного 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
Для чего использовать API Диска
• Работа с контентом пользователей
• Синхронизация данных между устройствами
• Хранение user-related данных приложений

70. 70
Спасибо за внимание!

71. 71
Роман Акинфеев
Разработчик back-end и REST API Яндекс.Диска
Клуб разработчиков:
Сервис «Полигон»: tech.yandex.ru/disk/poligon
clubs.ya.ru/apidisk/