Api devconf 2013

Проектирование API

Игорь Кузнецов, Undev, [email protected], @igkuz

1

пятница, 14 июня 13 г.

mailto:[email protected]


План

• Что такое API?• С чего начать проектирование?• Какими должны быть формат и структура ответа?

• Валидация больших структур• Обработка исключений

• Версионирование• Как написать клиент к вашему API?• Зачем все это нужно?

2


Что такое API?

3



Application Programming Interface

3



Application Programming InterfaceНабор методов, предоставляемых приложением(сервисом, классом, модулем) для использования во внешних программных продуктах

3


Что такое API на самом деле?

4


Интерфейс должен быть

5



• Интуитивно понятным

5



• Интуитивно понятным• Идеально продуманным с самого

начала

5



• Интуитивно понятным• Идеально продуманным с самого

начала

5


С чего начать проектирование?

6


С чего начать проектирование?

6


Просто начать

7



• Отделить API от остальной части проекта– /api

7



• Отделить API от остальной части проекта– /api

• rails generate controller api/posts

7


Бездумное следование

8


Бездумное следование

• В книгах и документации:

def index @people = People.all respond_to do |format| format.html format.xml { render xml: @people.to_xml } end end

8


Приводит к проблемам 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


Правильный путь

10



10

• respond_with + ( jbuilder || RABL || Action Model Serializers)



10

• respond_with + ( jbuilder || RABL || Action Model Serializers)

• структура и формат определяются во view или отдельном объекте


Возможный ответ

11

GitHub Instagram Foursquare


Возможный ответ

12

GitHub Instagram Foursquare


Что взять?

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: listend


Сложные структуры в ответе

14


Сложные структуры в ответе

14

# @return [Hash] Updated subscriber object # @example # { # "id": 1, # "email": "[email protected]", # "first_name": "Name#1", # "last_name": "Name#2", # "organization": "Organization#1", # "accreditation": "Accreditation#1", # "unisender_state": "unprocessed", # "highrise_state": "unprocessed" # } def update_subscriber # some code end




15

JSON Schema


15

"$schema": "http://json-‐schema.org/draft-‐04/schema#", "title": "List", "type": "object", "required": ["id", "name "], "properties": { "id": { "description": "Lists unique identifier", "type": "integer" }, "name": { "description": "Lists name in project", "type": "string" } }

JSON Schema


16

В результате


16

В результате

# @return [Hash] Updated subscriber object # @example # Link: http://yoursite.com/your_schema.json

def update_subscriber # some code end

• Gem: json-schema• https://github.com/hoxworth/json-schema


https://github.com/hoxworth/json-schema

https://github.com/hoxworth/json-schema

Пагинация

17


Пагинация

17

• Kaminari• https://github.com/amatsuda/kaminari

def index @lists = List.active. page(params[:page]).per(params[:per])

respond_with @lists end


https://github.com/amatsuda/kaminari

https://github.com/amatsuda/kaminari

Выборка, сортировка

18


Выборка, сортировка

18

• Ransack• https://github.com/ernie/ransack

def index @search = List.ransack(params[:search]) @lists = @search.result.page(params[:page]) respond_with @lists end


https://github.com/ernie/ransack

https://github.com/ernie/ransack

Обработка ошибок

19



19

• Одно из самых важных мест в API



19


• Отдавать правильные статус коды



19



• Присылать человеческие описания ошибок



19



• Присылать человеческие описания ошибок


Состояние API

20



20

• Все хорошо - success(200)



20


• Клиент прислал что-то не то - client error (400)



20


• Клиент прислал что-то не то - client error (400)

• Сервер сделал что-то не то - server error (500)


Варианты

21


Варианты

21

• 8-10 статус кодов на все случаи жизни


Варианты

21

• 8-10 статус кодов на все случаи жизни

• Улыбаемся и машем


Примеры старших

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"}


Exceptions App

23


Exceptions App

23

• application.rb:

– config.exceptions_app = self.routes


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"


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


Версионирование

25



25

• У API обязана быть версия



25


• Headers vs Urls



25


• Headers vs Urls

• Url:

– http://exmaple.com/v1/users?access_token=...


http://exmaple.com/v1/users?access_token=



25


• Headers vs Urls

• Url:

– http://exmaple.com/v1/users?access_token=...

• Headers:

– X-Example-Api-Version: 1.2




Сколько версий поддерживать

26



26

• Минимум 1 версию назад



26

• Минимум 1 версию назад

• Зависит от бизнес требований


Best practices || Тест на адекватность

27



27

• Библиотека для работы с API



27

• Библиотека для работы с API

• Если вам сложно написать клиент для вашего API, стоит серьезно задуматься


API Client

28


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


https://github.com/mwunsch/weary

https://github.com/mwunsch/weary

http://host.com/path/to/resource

http://host.com/path/to/resource

Зачем нужно делать хорошее API?

29



29

• Залог успешного общения с вашими пользователями



29


• Неявное вложение в рекламу



29


• Неявное вложение в рекламу

• Вложение в будущее проекта


Вопросы?

30


Documents

Api devconf 2013