Введение в REST API

Transcript

1. Oleg Zinchenko
   oleg@exercise.com
   Введение в REST API
   Подходы к генерации API документации
   

   View Slide

2. О себе
   Symfony разработчик с 2009 года
   TeamLead в Exercise.com
   Продвигаю Symfony2 в массы
   https://twitter.com/1cdecoder
   https://github.com/cystbear
   http://cystbear.tumblr.com/
   

   View Slide

3. Oleg Zinchenko
   Exercise.com
   Программы
   Питание
   Упражнения
   Видео
   Советы тренера
   Френды, лайки
   

   View Slide

4. Oleg Zinchenko
   REST
   REpresentational State Transfer
   Over HTTP
   State-less
   Кеширование
   Передача состояний
   

   View Slide

5. Oleg Zinchenko
   REST
   ACTIONS (HTTP METHODS)
   GET
   POST
   PUT/PATCH
   DELETE
   

   View Slide

6. Oleg Zinchenko
   REST
   RESTful web API
   forbidden
   /api/v1/orders/12/delete
   GET
   /api/v1/orders/12
   DELETE
   /api/v1/orders/12
   PUT
   /api/v1/orders/12
   GET
   /api/v1/orders
   POST
   /api/v1/orders
   GET
   

   View Slide

7. Oleg Zinchenko
   Задача
   

   View Slide

8. Oleg Zinchenko
   Задача
   {
   "firstName": "Иван",
   "lastName": "Иванов",
   "address": {
   "streetAddress": "Московское ш., 101, кв.101",
   "city": "Ленинград",
   "postalCode": 101101
   },
   "phoneNumbers": [
   "812 123-1234",
   "916 123-4567"]
   }
   
   Иван
   Иванов
   Московское ш., 101, кв.101
   Ленинград
   101101
   
   
   812 123-1234
   916 123-4567
   
   
   

   View Slide

9. Oleg Zinchenko
   Bundles
   FOSRestBundle
   FOSRest
   JMSSerializerBundle
   jms/metadata
   

   View Slide

10. Oleg Zinchenko
    2 Kernels
    AppKernel
    ApiKernel
    Разный набор конфигов
    Разный набор бандлов
    

    View Slide

11. Oleg Zinchenko
    authentication + authorization
    authentication + authorization
    

    View Slide

12. Oleg Zinchenko
    Authentication
    http://www.xml.com/pub/a/2003/12/17/dive.html
    

    View Slide

13. Oleg Zinchenko
    Serialization
    Serializer map
    Demo\Acme\Document\Food:
    exclusion_policy: ALL
    properties:
    calories:
    expose: true
    caloriesPerServing:
    expose: true
    caloriesPerGram:
    expose: true
    caloriesPerFluidOunce:
    expose: true
    measurement:
    expose: true
    servingOptions:
    expose: true
    callback_methods:
    pre_serialize: [prepareMeasurement, prepareServingOptions]
    

    View Slide

14. Oleg Zinchenko
    Serialization
    Object Handlers
    {
    "id": "4fb1fb87944c4c0e240004de",
    "slug": "minimalist-article",
    "title": "Minimalist article",
    "updated_at": "2012-05-15T09:45:26+0300",
    "summary": "Minimalist summary",
    "body": "Minimalist body",
    "main_image": "http://e.com/upl/art/thum/parrot.mobile_client_medium.v1.jpg"
    }
    

    View Slide

15. Oleg Zinchenko
    Тестирование
    Behat
    Buzz + aka WebApiContext
    Scenario: /foods get list of food. Pagination supported.
    Given I authorized as: "fred"
    When I make "GET" request to the "/api/v1/foods"
    Then the response status code should be: "200"
    And the response body should be similar to JSON:
    """
    [{"id":"4fb1fb8f944c4c0e24000622","slug":"bittermelon-cooked-a… }]
    """
    

    View Slide

16. Oleg Zinchenko
    Документация
    Hippo doc
    Swagger
    NelmioApiDocBundle
    

    View Slide

17. Oleg Zinchenko
    Документация
    http://api.jirafe.com/
    Hippo doc
    

    View Slide

18. Oleg Zinchenko
    Документация
    Swagger
    http://swagger.wordnik.com/
    apis: [{
    path: "/pet.{format}/{petId}",
    description: "Operations about pets",
    operations: [{
    httpMethod: "GET",
    nickname: "getPetById",
    responseClass: "Pet",
    parameters: [...]
    summary: "Find pet by its unique ID"
    notes: "Only Pets which you have permission to see will be returned",
    errorResponses: [...]
    }]
    }
    

    View Slide

19. Oleg Zinchenko
    Документация
    Swagger
    http://swagger.wordnik.com/
    

    View Slide

20. Oleg Zinchenko
    Документация
    NelmioApiDocBundle
    /**
    * This the documentation description of your method, it will appear
    * on a specific pane. It will read all the text until the first
    * annotation.
    *
    * @ApiDoc(
    * resource=true,
    * description="This is a description of your API method",
    * filters={
    * {"name"="a-filter", "dataType"="integer"},
    * {"name"="another-filter", "dataType"="string", "pattern"="(foo|bar) ASC|DESC"}
    * }
    * )
    */
    public function getAction()
    {
    }
    https://github.com/nelmio/NelmioApiDocBundle
    

    View Slide

21. Oleg Zinchenko
    Документация
    NelmioApiDocBundle
    https://github.com/nelmio/NelmioApiDocBundle
    

    View Slide

22. Oleg Zinchenko
    Спасибо
    Вопросы?
    

    View Slide