Api devconf 2013

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

Игорь Кузнецов, Undev, 2013igkuznetsov@gmail.com, @igkuz

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

План

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

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

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

Что такое API?

Application Programming Interface

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

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

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

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

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

начала

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

начала

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

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

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

• rails generate controller api/posts

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

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

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

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

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

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

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

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

GitHub Instagram Foursquare

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

GitHub Instagram Foursquare

Что взять?

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

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

# @return [Hash] Updated subscriber object # @example # { # "id": 1, # "email": "123@example.com", # "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

JSON Schema

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

В результате

# @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

Пагинация

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

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

respond_with @lists end

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

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

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

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

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

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

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

Состояние API

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

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

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

Варианты

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

Варианты

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

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

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

• 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

• application.rb:

– config.exceptions_app = self.routes

Exceptions App

• 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

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

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

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

• Headers vs Urls

• Url:

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

• Headers vs Urls

• Url:

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

• Headers:

– X-Example-Api-Version: 1.2

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

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

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

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

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

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

API Client

• 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

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

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

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

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

Вопросы?

Api devconf 2013

Documents

Devconf 2014 Трассировка событий при логировании

AnkaraJUG Nisan 2013 - Java Persistance API

Mysql replication DevConf 2012

Federico Procaccini DevConf 2014

Session Techdays 2013 Azure Service Management API

Api - mix it 2013

Anaconda DevConf 2013

Доклад Сергея Аверина на DevConf 2013. "Распространенные ошибки применения баз данных"

Devconf-2015 Тестируем инфраструктуру как код

Чат-боты: экосистема - Влад Гафаров - митап на DevConf

Pinboard + pinba / Как организовать мониторинг сотни PHP-проектов (Devconf 2014)

Twitter API, Streaming and SharePoint 2013

Test-driven infra - devconf

E Kokovikhin - devconf 2012

API 17H 2013 hotstabs

DevConf 2015. HTML5 Web Components: следующий шаг к модульности вашего проекта

Правильная работа с часовыми поясами в Rails приложении — DevConf 2015

174704528-API-spec-5L-2013 (1).pdf

Encom Aurora - Александр Попов - митап на DevConf

Blend Web Mix 2013 : Concevoir son API