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.

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?

7. Porque é legal:-)

8. Separação de interesses

9. Manutenção

10. Escalar o desenvolvimento

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"
}
}

25. Richardson Maturity Model

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

29. URL's
Identificação dos Recursos

30. Endpoint
https://ufo-api.dominio.com
https://dominio.com/ufo-api
https://api.ufo-api.com

31. Versionamento
3 jeitos de fazer
1. URL
2. QUERY STRING
3. HEADER [custom ou Accept]

32. Versionamento via URL
https://api.ufo-api.com/v1/casos

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

50. Filtrando resultados
/casos?pais=brasil

51. Ordenando resultados
/casos?sort=-ano,+nome
- descending
+ ascending

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

54. Ferramentas úteis

55. Prototipagem
https://apiary.io/

56. Documentando sua API
Swagger
http://swagger.io/

57. Frameworks
FRAPI
http://getfrapi.com
APIGILITY
http://apigility.org
PhlyRestfully
https://phlyrestfully.
readthedocs.org/en/latest/
TONIC
http://www.peej.co.
uk/tonic/
Silex et al

58. Plataformas na nuvem (oh)
http://restlet.com/products/apispark/
http://apigee.com/about/

59. Perguntas, dúvidas, sugestões
? ? ? ? ?

60. Avalie esta palestra!
https://joind.in/14357
Obrigado!!!!