2. План
• Что такое API?
• С чего начать проектирование?
• Какими должны быть формат и структура ответа?
• Валидация больших структур
• Обработка исключений
• Версионирование
• Как написать клиент к вашему API?
• Зачем все это нужно?
2
пятница, 14 июня 13 г.
5. Что такое API?
Application Programming Interface
Набор методов, предоставляемых приложением(сервисом,
классом, модулем) для использования во внешних программных
продуктах
3
пятница, 14 июня 13 г.
6. Что такое API на самом деле?
4
пятница, 14 июня 13 г.
17. Бездумное следование
• В книгах и документации:
def
index
@people
=
People.all
respond_to
do
|format|
format.html
format.xml
{
render
xml:
@people.to_xml
}
end
end
8
пятница, 14 июня 13 г.
18. Приводит к проблемам
if
@category.save
respond_to
do
|format|
format.html
do
flash[:notice]
=
l(:notice_successful_create)
redirect_to_settings_in_projects
end
format.js
format.api
{
render
:action
=>
'show',
:status
=>
:created
}
end
else
respond_to
do
|format|
format.html
{
render
:action
=>
'new'}
format.js
{
render
:action
=>
'new'}
format.api
{
render_validation_errors(@category)
}
end
end
9
пятница, 14 июня 13 г.
21. Правильный путь
10
• respond_with + ( jbuilder || RABL || Action Model Serializers)
• структура и формат определяются во view или отдельном
объекте
пятница, 14 июня 13 г.
24. Что взять?
13
Foursquare + Instagram
json.meta
do
|json|
json.total
@lists.total_count
json.num_pages
@lists.num_pages
json.per_page
@per_page
end
json.items
@lists
do
|json,
list|
json.partial!
"maillist",
maillist:
list
end
пятница, 14 июня 13 г.
37. Обработка ошибок
19
• Одно из самых важных мест в API
• Отдавать правильные статус коды
пятница, 14 июня 13 г.
38. Обработка ошибок
19
• Одно из самых важных мест в API
• Отдавать правильные статус коды
• Присылать человеческие описания ошибок
пятница, 14 июня 13 г.
39. Обработка ошибок
19
• Одно из самых важных мест в API
• Отдавать правильные статус коды
• Присылать человеческие описания ошибок
пятница, 14 июня 13 г.
42. Состояние API
20
• Все хорошо - success(200)
• Клиент прислал что-то не то - client error (400)
пятница, 14 июня 13 г.
43. Состояние API
20
• Все хорошо - success(200)
• Клиент прислал что-то не то - client error (400)
• Сервер сделал что-то не то - server error (500)
пятница, 14 июня 13 г.
47. Примеры старших
22
• Facebook:
HTTP Status Code: 200
{"type" : "OauthException", "message":"(#803) Some
of the aliases you requested do not exist: foo.bar"}
• Github:
HTTP/1.1 404 Not Found
{"message": "Not Found"}
пятница, 14 июня 13 г.
50. Exceptions App
23
• application.rb:
– config.exceptions_app = self.routes
• routes.rb:
– match
'/404',
:to
=>
"errors#not_found"
– match
'/422',
:to
=>
"errors#unprocessable_entity"
– match
'/500',
:to
=>
"errors#internal_error"
пятница, 14 июня 13 г.
51. Exceptions App
24
class
ErrorsController
<
ApplicationController
respond_to
:json,
:html
def
not_found
#
some
code
here
end
def
internal_error
respond_with(...)
end
def
unprocessable_entity
#
some
code
here
end
end
пятница, 14 июня 13 г.
55. Версионирование
25
• У API обязана быть версия
• Headers vs Urls
• Url:
– http://exmaple.com/v1/users?access_token=...
пятница, 14 июня 13 г.
56. Версионирование
25
• У API обязана быть версия
• Headers vs Urls
• Url:
– http://exmaple.com/v1/users?access_token=...
• Headers:
– X-Example-Api-Version: 1.2
пятница, 14 июня 13 г.
61. Best practices || Тест на адекватность
27
• Библиотека для работы с API
пятница, 14 июня 13 г.
62. Best practices || Тест на адекватность
27
• Библиотека для работы с API
• Если вам сложно написать клиент для вашего API, стоит
серьезно задуматься
пятница, 14 июня 13 г.
64. API Client
28
• Weary
• https://github.com/mwunsch/weary
class
MyClass
<
Weary::Client
get
:resource,
"http://host.com/path/to/"
do
|resource|
resource.required
:api_token,
:id
resource.optional
:optional_parameter
end
end
пятница, 14 июня 13 г.
66. Зачем нужно делать хорошее API?
29
• Залог успешного общения с вашими пользователями
пятница, 14 июня 13 г.
67. Зачем нужно делать хорошее API?
29
• Залог успешного общения с вашими пользователями
• Неявное вложение в рекламу
пятница, 14 июня 13 г.
68. Зачем нужно делать хорошее API?
29
• Залог успешного общения с вашими пользователями
• Неявное вложение в рекламу
• Вложение в будущее проекта
пятница, 14 июня 13 г.
