JSON API: Não reinvente a roda

Existem diversos aspectos que devem ser priorizados ao se escrever uma API. Bom entendimento do domínio, arquitetura ideal, boa estratégia de testes, etc. Esses são alguns dos problemas reais e prioritários existentes. JSON API é uma ótima solução para evitar a perda de tempo tentando reinventar a roda durante a definição do design das respostas de sua aplicação. Nesta apresentação, alguns exemplos de uso, considerações/vantagens e dicas de como tornar a sua aplicação compatível sem (muita) dor.

Transcript

1. pen4education
   JSON API: não reinvente a roda
   Pedro Cavalheiro
   Trilha Web
   

   View Slide

2. pen4education
   Pedro Cavalheiro
   Desenvolvedor web há 6 anos, em sua
   maioria trabalhando com Ruby e PHP.
   Entusiasta por tecnologia como um todo,
   adora estudar novas ferramentas,
   linguagens e metodologias.
   Atualmente no Me Salva!.
   Infos em pecavalheiro.com
   

   View Slide

3. pen4education
   Did I hear API?
   

   View Slide

4. pen4education
   API
   • Application Programming Interface
   • Web Services (HTTP)
   • SOAP
   • REST
   • JSON
   

   View Slide

5. pen4education
   REST API
   • O que é importante?
   • Segurança/Autenticação
   • Documentação
   • Requisitos/Complexidade
   • Design de requisições/respostas
   • +
   

   View Slide

6. pen4education
   

   View Slide

7. pen4education
   bikeshed (noun)
   • (literally) An enclosed structure where bicycles
   may be stored.
   • (figuratively, technical jargon) A topic that is
   attracting debate ad nauseam, out of all proportion
   to its actual importance. Also bikeshedding, the
   process of futile investment of time and energy in
   discussion of marginal technical issues.
   

   View Slide

8. pen4education
   

   View Slide

9. pen4education
   Did I hear API?
   

   View Slide

10. pen4education
    Did I hear API?
    

    View Slide

11. pen4education
    JSON API
    • O que ele define?
    Just kidding!
    

    View Slide

12. pen4education
    • Como um cliente deve consultar, criar e/ou modificar
    recursos.
    • Verbos
    • Formato da URL/Filtros
    • Paginação
    • +
    • Como o servidor deve responder a estas requisições.
    • Estrutura de resposta
    • Status Code
    • +
    JSON API
    • O que ele define?
    

    View Slide

13. pen4education
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    {
    "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
    "title": "JSON API paints my bikeshed!",
    "body": "The shortest article. Ever.",
    "created": "2015-05-22T14:56:29.000Z",
    "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
    "author": {
    "data": {"id": "42", "type": "people"}
    }
    }
    }],
    "included": [
    {
    "type": "people",
    "id": "42",
    "attributes": {
    "name": "John",
    "age": 80,
    "gender": "male"
    }
    }
    ]
    }
    GET /articles?include=author HTTP/1.1
    

    View Slide

14. pen4education
    HTTP/1.1 200 OK
    Content-Type: application/vnd.api+json
    {
    "meta": {
    "total-pages": 13
    },
    "data": [
    {
    "type": "articles",
    "id": "3",
    "attributes": {
    "title": "JSON API paints my bikeshed!",
    "body": "The shortest article. Ever.",
    "created": "2015-05-22T14:56:29.000Z",
    "updated": "2015-05-22T14:56:28.000Z"
    }
    }
    ],
    "links": {
    "self": "http://example.com/articles?page[number]=3&page[size]=1",
    "first": "http://example.com/articles?page[number]=1&page[size]=1",
    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
    "next": "http://example.com/articles?page[number]=4&page[size]=1",
    "last": "http://example.com/articles?page[number]=13&page[size]=1"
    }
    }
    GET /articles?page[number]=3&page[size]=1 HTTP/1.1
    

    View Slide

15. pen4education
    HTTP/1.1 422 Unprocessable Entity
    Content-Type: application/vnd.api+json
    {
    "errors": [
    {
    "status": "422",
    "source": { "pointer": "/data/attributes/first-name" },
    "title": "Invalid Attribute",
    "detail": "First name must contain at least three characters."
    }
    ]
    }
    

    View Slide

16. pen4education
    JSON API
    • Implementação
    

    View Slide

17. pen4education
    • Client libraries
    • JavaScript, iOS, Ruby, PHP, Dart, Perl, Java, Android, R, Elm, .NET
    • Server libraries
    • PHP, Node.js, Ruby, Python, Go, .NET, Java, Scala, Elixir, Haskell,
    Perl, Vala
    JSON API
    • Implementação - jsonapi.org/implementations
    

    View Slide

18. pen4education
    Resumão
    • Calma! Ajuste uma parte de cada vez
    • JSON API não é “lei”, existem outros padrões:
    HAL, Siren, JSON-LD, Collection+JSON, etc
    • Adote padrões, eles facilitam nossa vida :)
    

    View Slide

19. pen4education
    Dúvidas?
    jsonapi.org
    pecavalheiro.com
    OBRIGADO!
    

    View Slide