разработка RESTful api with all bells and whistles
Download as PPTX, PDF0 likes306 views
Документ описывает разработку RESTful API для сервиса Яндекс.Диск, выделяя его структуру, принципы работы и преимущества. Основное внимание уделяется гипермедиа API, доступности ресурсов и использованию различных HTTP-методов. Включены примеры запросов и рекомендации по проектированию удобного и расширяемого API.
![21
Обычное API
# пусть у нас есть объект папки
print folder
{
“name”: “foo”,
“path”: “disk:/foo”,
“type”: “dir”
}
# удаляем папку
URL = 'https://cloud-api.yandex.net/v1/disk/resources'
query = {}
query['path'] = o['path']
query['permanently'] = True
qs = urlencode(query)
url = URL + '?' + qs
request('DELETE', url)
<Response [204]>](https://image.slidesharecdn.com/restfulapiwithallbellsandwhistles2-140606081130-phpapp01/85/RESTful-api-with-all-bells-and-whistles-21-320.jpg)
![22
Hypermedia API
# пусть у нас есть объект папки с HAL-ссылками
folder = request(o[‘method’], o[‘href’]).json()
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 = o[‘_links’][‘delete’]
request(action[‘method’], action[‘href’])
<Response [204]>](https://image.slidesharecdn.com/restfulapiwithallbellsandwhistles2-140606081130-phpapp01/85/RESTful-api-with-all-bells-and-whistles-22-320.jpg)
разработка RESTful api with all bells and whistles
- 1. 1
- 2. 2 Разработка RESTful API with all the bells and whistles Роман Акинфеев
- 3. 3 Яндекс.Диск — это сервис, который позволяет хранить файлы и обмениваться ими, а также предоставляет доступ к файлам с любого устройства, подключённого к интернету. 20 млн. зарегистрированных пользователей 10 млн. загружаемых в сутки файлов 7 млрд. файлов
- 4. 4 Yandex Disk APIs WebDAV Для работы с Диском, как с файловой системой RESTful API Для работы с Диском там, где WebDAV’а мало
- 5. 5 Задачи Простота изучения возможностей API Легко расширяемая функциональность Простота разработки под API
- 6. 6 RESTful API Яндекс Диска Понятная и логичная структура Hypermedia API Self-descriptive & Machine-readable API
- 7. 7 Что такое REST? Просто набор принципов Никаких готовых решений
- 8. 8 Клиент-сервер и интерфейс Клиент и сервер знают интерфейс Клиент и сервер не знают друг друга Профит Много клиентов хороших и разных Сервер не замечает, как обновляются клиенты Клиенты не замечают, как обновляется сервер
- 9. 9 Stateless Сервер не хранит никакой информации о состоянии клиента между запросами Нет соединений Нет сессий Нет истории операций клиента Профит Бэкэнд легко масштабируется Клиент не беспокоится ни о чём между запросами
- 10. 10 Кэшируемость и многослойность Сервер сообщает, что и как кэшировать Клиент может не соединяться напрямую с сервером Профит Возможность снизить нагрузку на бэкэнд Возможность работать с кэшем на клиенте
- 11. 11 Рецепт RESTful API Яндекс Диска
- 12. 12 Ресурсы Система оперирует ресурсами Ресурсы имеют чёткую структуру URL – уникальный идентификатор ресурса Ресурсы API Диска: Файлы и папки – resources Асинхронные операции – operations
- 13. 13 URL ресурсов URL группируются в нэймспэйсы /disk URL коллекции ресурсов всегда во множественном числе /disk / resources /disk / operations URL коллекции + идентификатор = URL ресурса /disk / resources ? path={path} /disk / operations ? id={id} /pets / kittens / {name}
- 14. 14 HTTP-методы Основные CRUD-операции: GET, POST, PUT, DELETE
- 15. 15 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 – подскажет поддерживаемые ресурсом методы
- 16. 16 Когда CRUD мало Копирование и Перемещение Не идемпотентны Не безопасны Надо использовать POST, но метод один и ресурс один На помощь приходят Ad Hoc-методы! POST /disk/resources/ copy ? path={path}&from={from} POST /disk/resources/ move ? path={path}&from={from}
- 17. 17 The Bells And Whistles RESTful API Яндекс Диска
- 18. 18 Hypermedia API Hypermedia as the Engine of Application State Клиент должен взаимодействовать с сервером посредством гипермедиа-контролов, получаемых от сервера. Hypermedia-контролы Гиперссылки Формы (не HTML формы ;) Профит Клиент не дёргает захардкоденные URL Клиент переходит по ссылкам
- 19. 19 Hypermedia API Collection+JSON HAL DocJSON JSON API JSON Hyperschema HTML
- 20. 20 Hypertext Application Language Есть draft RFC-стандарта Чрезвычайно прост Уже встречается в публичных API MIME-type: application/hal+json Благодаря HAL Клиент знает, что и как может сделать с объектом Сервер может управлять набором доступных действий
- 21. 21 Обычное API # пусть у нас есть объект папки print folder { “name”: “foo”, “path”: “disk:/foo”, “type”: “dir” } # удаляем папку URL = 'https://cloud-api.yandex.net/v1/disk/resources' query = {} query['path'] = o['path'] query['permanently'] = True qs = urlencode(query) url = URL + '?' + qs request('DELETE', url) <Response [204]>
- 22. 22 Hypermedia API # пусть у нас есть объект папки с HAL-ссылками folder = request(o[‘method’], o[‘href’]).json() 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 = o[‘_links’][‘delete’] request(action[‘method’], action[‘href’]) <Response [204]>
- 23. 23 Self-describing & Machine-readable Машиночитаемые способы описания REST API RAML WADL JSON Schema + JSON HyperSchema Swagger IO Docs Apiary Blueprints
- 24. 24 Swagger Описывает API в виде JSON Развивается как стандарт Прост для понимания Имеет экосистему инструментов
- 25. 25 Профит от Swagger Автогенерация частей нативных SDK Универсальные Swagger-клиенты Готовый open source UI для API
- 28. 28 Что в итоге получилось Простая расширяемая структура Удобная навигация по API с помощью ссылок Самодокументируемость и машиночитаемость
- 29. 29 Рецепт здорового API Структура в виде ресурсов и операций над ними Доступ к объектам через коллекции Старайтесь придерживаться RFC 2616 Используйте Ad Hoc-методы там где не хватает HTTP Добавляйте в API hypermedia-контролы HAL – http://stateless.co/hal_specification.html Описывайте API с помощью машиночитаемых форматов Swagger – https://helloreverb.com/developers/swagger
- 30. 30 Для чего использовать API Диска Работа с контентом пользователей Синхронизация данных между устройствами Хранение user-related данных приложений
- 32. 32 Роман Акинфеев Разработчик back-end и REST API Яндекс.Диска Клуб разработчиков: http://clubs.ya.ru/apidisk/ Сервис «Полигон»: api.yandex.ru/disk/polygon