Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Введение в REST API

Введение в REST API

Oleg Zinchenko

November 30, 2012
Tweet

More Decks by Oleg Zinchenko

Other Decks in Programming

Transcript

  1. Oleg Zinchenko
    [email protected]
    Введение в REST API
    Подходы к генерации API документации

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

  7. Oleg Zinchenko
    Задача

    View full-size 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 full-size slide

  9. Oleg Zinchenko
    Bundles
    FOSRestBundle
    FOSRest
    JMSSerializerBundle
    jms/metadata

    View full-size slide

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

    View full-size slide

  11. Oleg Zinchenko
    authentication + authorization
    authentication + authorization

    View full-size slide

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

    View full-size 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 full-size 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 full-size 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 full-size slide

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

    View full-size slide

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

    View full-size 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 full-size slide

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

    View full-size 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 full-size slide

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

    View full-size slide

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

    View full-size slide