APIs Rest(Ful): como fazer, por Alex Piaz
3 gostaram937 visualizações
Este documento fornece uma introdução às APIs RESTful, discutindo seus principais conceitos e padrões, incluindo recursos, verbos HTTP, HATEOAS, paginação, autenticação e ferramentas para desenvolvimento e documentação de APIs. O documento também apresenta um exemplo prático de uma API fictícia sobre avistamentos de OVNIs.
![Versionamento
3 jeitos de fazer
1. URL
2. QUERY STRING
3. HEADER [custom ou Accept]](https://image.slidesharecdn.com/alexpiaz-apisrestful-150508214009-lva1-app6892/85/APIs-Rest-Ful-como-fazer-por-Alex-Piaz-31-320.jpg)
![Recursos são coisas!
Substantivos em vez de verbos
/getCaso/1 /caso/ver/1
/casos/1
[ VERBOS HTTP ]
plural em vez de singular
s [ MEDIA TYPES ]](https://image.slidesharecdn.com/alexpiaz-apisrestful-150508214009-lva1-app6892/85/APIs-Rest-Ful-como-fazer-por-Alex-Piaz-36-320.jpg)
![2 tipos de recurso
Collection /casos [GET POST PUT]
Document /casos/{x} [GET PUT DELETE]
Complexidade vai para a query string!](https://image.slidesharecdn.com/alexpiaz-apisrestful-150508214009-lva1-app6892/85/APIs-Rest-Ful-como-fazer-por-Alex-Piaz-38-320.jpg)
![Obtendo um recurso
200 OK
Content-type: application/json
[{
"id": 1,
"nome": "O caso Varginha",
"descricao": "Incidente de Varginha...",
"_links": {
"self": {
"href": "/casos/1"
}
}
},
…
]
200 OK
Content-type: application/xml
<casos>
<caso>
<id>1</id>
<nome>O caso Varginha</nome>
<descricao>Incidente de Varginha…</descricao>
<link rel=”self” href=”/casos/1” />
<link rel=”parent” href=”/casos” />
<link rel=”next” href=”/casos/2” />
</caso>
…
</casos>
#RESPONSE](https://image.slidesharecdn.com/alexpiaz-apisrestful-150508214009-lva1-app6892/85/APIs-Rest-Ful-como-fazer-por-Alex-Piaz-42-320.jpg)
APIs Rest(Ful): como fazer, por Alex Piaz
- 2. API's ReST(Ful) Dicas, truques e subversão :-) Alex Piaz - Abril 2015
- 3. O Palestrante (oh) 18+ WWW 14+ PHP / 10+ Drupal 09+ ISA https://about.me/alexpiaz
- 4. API Application Programming Interface Define como o Software Interage web API API com transporte baseado em HTTP ReST Soap XML-RPC
- 5. HTTP Leia a RFC2616 até enjoar!
- 6. Por que API?
- 9. Manutenção
- 11. Estratégias (ou como fazer a sua api sair do papel)
- 12. API-First Uma app nova? Faça a API primeiro! http://apievangelist.com/
- 13. API-Last Converta seu legado em API!
- 14. API-Never Se for só um website. NUNCA É SÓ UM WEBSITE!
- 15. Uma API é um PACTO Cópia do “suposto” pacto assinado entre o pe. Urbain Grandier e vários capetas! http://en.wikipedia.org/wiki/Urbain_Grandier
- 16. ReST Representational State Transfer Estilo arquitetural da web
- 17. ReST(Ful)
- 18. ReST Constraints Client-Server Stateless Cache Uniform Interface Layered System Code-On-Demand* Uniform Interface
- 19. Identificação dos recursos http://ufo-api.zaip.net/v1/casos/o-caso-varginha + VERBOS HTTP
- 20. Manipulação de recursos através de suas representações
- 21. Mensagens auto descritivas HTTP Status codes Mime types/media types
- 22. Hypermedia HATEOAS Hypermedia as the engine of the application state <recurso> <id>1</id> …. <links> <link rel=”self” href=”/recursos/1” /> <link rel=”parent” href=”/recursos” /> <link rel=”next” href=”/recursos/2” /> </links> </recurso>
- 23. JSON hypermedia? NO. NÃO. IIE. NON. NICHT E agora? HAL - Hypertext Application Language http://stateless.co/hal_specification.html JSON-LD http://www.w3.org/TR/json-ld/
- 24. Hypermedia HAL application/json ou application/json+hal _links: { self: { href: "/recursos/1" }, parent: { href: "/recursos" } }
- 26. Projetando API's
- 27. Exemplo: UFO API Objetivo Disponibilizar informações sobre casos de ocorrências de avistamento / contato com ufos
- 28. UFO API :: Modelo Caso ID Nome Descrição Ano País
- 31. Versionamento 3 jeitos de fazer 1. URL 2. QUERY STRING 3. HEADER [custom ou Accept]
- 33. Versionamento via QUERY STRING https://api.ufo-api.com/casos?v=1
- 34. Versionamento via HTTP HEADER X-API-Version:1 Accept:application/vnd.ufoapi.v1+json
- 35. A parada é ter um contrato estável!
- 36. Recursos são coisas! Substantivos em vez de verbos /getCaso/1 /caso/ver/1 /casos/1 [ VERBOS HTTP ] plural em vez de singular s [ MEDIA TYPES ]
- 37. Resource Archetypes Collection /v1/casos Instance / Document /v1/casos/1 Store /v1/casos/favoritos/alex Controller /autenticar Alias /v1/casos/brasil == /v1/casos?pais=Brasil
- 38. 2 tipos de recurso Collection /casos [GET POST PUT] Document /casos/{x} [GET PUT DELETE] Complexidade vai para a query string!
- 39. Negociação de Conteúdo “Quem pode, manda. Quem tem juízo, obedece.” Cliente diz o que quer receber. Você se vira pra entregar! Request Accept: application/json;q=0.9,application/xml;q=0.8,*/*;q=0.4 Response Content-type: application/json http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
- 40. E se eu não puder entregar? Request Accept: application/json;q=1,text/xml;q=0.8 ++ EU SÓ TENHO text/csv ++ Response HTTP/1.1 406 Not Acceptable
- 41. Obtendo um recurso GET /casos Accept: application/json GET /casos Accept: application/xml GET /casos.json .xml .bla bla bla #REQUEST
- 42. Obtendo um recurso 200 OK Content-type: application/json [{ "id": 1, "nome": "O caso Varginha", "descricao": "Incidente de Varginha...", "_links": { "self": { "href": "/casos/1" } } }, … ] 200 OK Content-type: application/xml <casos> <caso> <id>1</id> <nome>O caso Varginha</nome> <descricao>Incidente de Varginha…</descricao> <link rel=”self” href=”/casos/1” /> <link rel=”parent” href=”/casos” /> <link rel=”next” href=”/casos/2” /> </caso> … </casos> #RESPONSE
- 43. Se o recurso não existir... GET /casos/um-caso-que-nao-existe HTTP/1.1 404 Not Found
- 44. Criando um novo recurso #REQUEST POST /casos Content-Type: application/json { "nome": "A noite oficial dos OVNIS no Brasil.", "descricao": "Noite Oficial dos OVNIs é um termo adotado por ufólogos brasileiros para descrever a aparição de vários Objetos Voadores Não- Identificados (OVNI) sobre o Brasil de acordo com informações do Comando da Aeronáutica do Brasil.", “ano”: 1986, “pais”: “Brasil” }
- 45. Criando um novo recurso #RESPONSE 201 Created Location: /casos/3 Content-Type: application/json { "message”: “Caso criado com sucesso!” }
- 46. Criando um novo recurso #RESPONSE 201 Created Location: /casos/3 Content-Type: application/json { "id": 3, "nome": "A noite oficial dos OVNIS no Brasil.", "descricao": "Noite Oficial dos OVNIs é um termo adotado por ufólogos brasileiros para descrever a aparição de vários Objetos Voadores Não- Identificados (OVNI) sobre o Brasil de acordo com informações do Comando da Aeronáutica do Brasil.", “ano”: 1986, “pais”: “Brasil” }
- 47. Atualizando um recurso #REQUEST PUT /casos/1 Content-Type: application/json {......} #RESPONSE 204 NO CONTENT Content-Typo: application/json Location: /casos/1 Para atualizaçoes parciais, use PATCH
- 48. Excluindo um recurso DELETE /casos/2 200 OK { "mensagem": "Caso excluído” }
- 49. Paginando resultados Use o HTTP Header “Link” http://tools.ietf.org/html/rfc5988#page-6 Link: <https://api.ufo-api.com/v1/casos?offset=15&limit=5>; rel="next", <https://https://api.ufo-api.com/v1/casos?offset=50&limit=3>; rel="last", <https://https://api.ufo-api.com/v1/casos?offset=0&limit=5>; rel="first", <https://https://api.ufo-api.com/v1/casos?offset=5&limit=5>; rel="prev", Total de resultados? Custom Header! X-Total-Count: 120
- 52. Restringindo campos /casos/3?fields=nome,ano { "id": 3, "nome": "O caso Varginha", "ano": 1996, ... }
- 53. Autenticação / Controle de Acesso Basic Auth Digest Auth oAuth2 WWW-Authenticate IP / Rede
- 58. Plataformas na nuvem (oh) http://restlet.com/products/apispark/ http://apigee.com/about/
- 59. Perguntas, dúvidas, sugestões ? ? ? ? ?