Api devconf 2013

337 views

Published on

0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
337
On SlideShare
0
From Embeds
0
Number of Embeds
60
Actions
Shares
0
Downloads
6
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Api devconf 2013

  1. 1. Проектирование APIИгорь Кузнецов, Undev, 2013igkuznetsov@gmail.com, @igkuz1пятница, 14 июня 13 г.
  2. 2. План• Что такое API?• С чего начать проектирование?• Какими должны быть формат и структура ответа?• Валидация больших структур• Обработка исключений• Версионирование• Как написать клиент к вашему API?• Зачем все это нужно?2пятница, 14 июня 13 г.
  3. 3. Что такое API?3пятница, 14 июня 13 г.
  4. 4. Что такое API?Application Programming Interface3пятница, 14 июня 13 г.
  5. 5. Что такое API?Application Programming InterfaceНабор методов, предоставляемых приложением(сервисом,классом, модулем) для использования во внешних программныхпродуктах3пятница, 14 июня 13 г.
  6. 6. Что такое API на самом деле?4пятница, 14 июня 13 г.
  7. 7. Интерфейс должен быть5пятница, 14 июня 13 г.
  8. 8. Интерфейс должен быть• Интуитивно понятным5пятница, 14 июня 13 г.
  9. 9. Интерфейс должен быть• Интуитивно понятным• Идеально продуманным с самогоначала5пятница, 14 июня 13 г.
  10. 10. Интерфейс должен быть• Интуитивно понятным• Идеально продуманным с самогоначала5пятница, 14 июня 13 г.
  11. 11. С чего начать проектирование?6пятница, 14 июня 13 г.
  12. 12. С чего начать проектирование?6пятница, 14 июня 13 г.
  13. 13. Просто начать7пятница, 14 июня 13 г.
  14. 14. Просто начать• Отделить API от остальной части проекта– /api7пятница, 14 июня 13 г.
  15. 15. Просто начать• Отделить API от остальной части проекта– /api• rails generate controller api/posts7пятница, 14 июня 13 г.
  16. 16. Бездумное следование8пятница, 14 июня 13 г.
  17. 17. Бездумное следование• В книгах и документации:def  index        @people  =  People.all          respond_to  do  |format|            format.html            format.xml  {  render  xml:  @people.to_xml  }        end    end8пятница, 14 июня 13 г.
  18. 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        end9пятница, 14 июня 13 г.
  19. 19. Правильный путь10пятница, 14 июня 13 г.
  20. 20. Правильный путь10• respond_with + ( jbuilder || RABL || Action Model Serializers)пятница, 14 июня 13 г.
  21. 21. Правильный путь10• respond_with + ( jbuilder || RABL || Action Model Serializers)• структура и формат определяются во view или отдельномобъектепятница, 14 июня 13 г.
  22. 22. Возможный ответ11GitHub Instagram Foursquareпятница, 14 июня 13 г.
  23. 23. Возможный ответ12GitHub Instagram Foursquareпятница, 14 июня 13 г.
  24. 24. Что взять?13Foursquare + Instagramjson.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 июня 13 г.
  25. 25. Сложные структуры в ответе14пятница, 14 июня 13 г.
  26. 26. Сложные структуры в ответе14    #  @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пятница, 14 июня 13 г.
  27. 27. 15JSON Schemaпятница, 14 июня 13 г.
  28. 28. 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пятница, 14 июня 13 г.
  29. 29. 16В результатепятница, 14 июня 13 г.
  30. 30. 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пятница, 14 июня 13 г.
  31. 31. Пагинация17пятница, 14 июня 13 г.
  32. 32. Пагинация17• Kaminari• https://github.com/amatsuda/kaminaridef  index        @lists  =  List.active.                                    page(params[:page]).per(params[:per])        respond_with  @lists    endпятница, 14 июня 13 г.
  33. 33. Выборка, сортировка18пятница, 14 июня 13 г.
  34. 34. Выборка, сортировка18• Ransack• https://github.com/ernie/ransack    def  index        @search  =  List.ransack(params[:search])        @lists  =  @search.result.page(params[:page])            respond_with  @lists    endпятница, 14 июня 13 г.
  35. 35. Обработка ошибок19пятница, 14 июня 13 г.
  36. 36. Обработка ошибок19• Одно из самых важных мест в APIпятница, 14 июня 13 г.
  37. 37. Обработка ошибок19• Одно из самых важных мест в API• Отдавать правильные статус кодыпятница, 14 июня 13 г.
  38. 38. Обработка ошибок19• Одно из самых важных мест в API• Отдавать правильные статус коды• Присылать человеческие описания ошибокпятница, 14 июня 13 г.
  39. 39. Обработка ошибок19• Одно из самых важных мест в API• Отдавать правильные статус коды• Присылать человеческие описания ошибокпятница, 14 июня 13 г.
  40. 40. Состояние API20пятница, 14 июня 13 г.
  41. 41. Состояние API20• Все хорошо - success(200)пятница, 14 июня 13 г.
  42. 42. Состояние API20• Все хорошо - success(200)• Клиент прислал что-то не то - client error (400)пятница, 14 июня 13 г.
  43. 43. Состояние API20• Все хорошо - success(200)• Клиент прислал что-то не то - client error (400)• Сервер сделал что-то не то - server error (500)пятница, 14 июня 13 г.
  44. 44. Варианты21пятница, 14 июня 13 г.
  45. 45. Варианты21• 8-10 статус кодов на все случаи жизнипятница, 14 июня 13 г.
  46. 46. Варианты21• 8-10 статус кодов на все случаи жизни• Улыбаемся и машемпятница, 14 июня 13 г.
  47. 47. Примеры старших22• Facebook:HTTP Status Code: 200{"type" : "OauthException", "message":"(#803) Someof the aliases you requested do not exist: foo.bar"}• Github:HTTP/1.1 404 Not Found{"message": "Not Found"}пятница, 14 июня 13 г.
  48. 48. Exceptions App23пятница, 14 июня 13 г.
  49. 49. Exceptions App23• application.rb:– config.exceptions_app = self.routesпятница, 14 июня 13 г.
  50. 50. Exceptions App23• 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. 51. Exceptions App24class  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 г.
  52. 52. Версионирование25пятница, 14 июня 13 г.
  53. 53. Версионирование25• У API обязана быть версияпятница, 14 июня 13 г.
  54. 54. Версионирование25• У API обязана быть версия• Headers vs Urlsпятница, 14 июня 13 г.
  55. 55. Версионирование25• У API обязана быть версия• Headers vs Urls• Url:– http://exmaple.com/v1/users?access_token=...пятница, 14 июня 13 г.
  56. 56. Версионирование25• У API обязана быть версия• Headers vs Urls• Url:– http://exmaple.com/v1/users?access_token=...• Headers:– X-Example-Api-Version: 1.2пятница, 14 июня 13 г.
  57. 57. Сколько версий поддерживать26пятница, 14 июня 13 г.
  58. 58. Сколько версий поддерживать26• Минимум 1 версию назадпятница, 14 июня 13 г.
  59. 59. Сколько версий поддерживать26• Минимум 1 версию назад• Зависит от бизнес требованийпятница, 14 июня 13 г.
  60. 60. Best practices || Тест на адекватность27пятница, 14 июня 13 г.
  61. 61. Best practices || Тест на адекватность27• Библиотека для работы с APIпятница, 14 июня 13 г.
  62. 62. Best practices || Тест на адекватность27• Библиотека для работы с API• Если вам сложно написать клиент для вашего API, стоитсерьезно задуматьсяпятница, 14 июня 13 г.
  63. 63. API Client28пятница, 14 июня 13 г.
  64. 64. API Client28• Weary• https://github.com/mwunsch/wearyclass  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 г.
  65. 65. Зачем нужно делать хорошее API?29пятница, 14 июня 13 г.
  66. 66. Зачем нужно делать хорошее API?29• Залог успешного общения с вашими пользователямипятница, 14 июня 13 г.
  67. 67. Зачем нужно делать хорошее API?29• Залог успешного общения с вашими пользователями• Неявное вложение в рекламупятница, 14 июня 13 г.
  68. 68. Зачем нужно делать хорошее API?29• Залог успешного общения с вашими пользователями• Неявное вложение в рекламу• Вложение в будущее проектапятница, 14 июня 13 г.
  69. 69. Вопросы?30пятница, 14 июня 13 г.

×