O documento discute APIs web e as diferenças entre SOAP e RESTful. Também explica como RESTful funciona usando verbos HTTP, URLs, URIs e padrões de resposta.

1. Web APIs

2. EvaldoBarbosa
Analista de Sistemas
Presidente do PHP Maranhão
Membro da diretoria da ABRAPHP

3. SOAP: Protocolo baseado em XML,
geralmente utilizado por aplicações em
Java.
RESTFul: Aplicações geralmente baseadas
em JSON e utilizada por diversas
linguagens.
SOAP x RESTful

4. Representational State Transfer
(REST)
Client-server
Stateless
Uniform interface
Cache (client cache, server cache)

5. Por volta de 2000, por Roy Fielding como
tese de doutorado.
Época em que, com a colaboração dos
colegas, estava escrevendo as
especificaçoes do HTTP 1.1.
Origem do REST

6. Quem usa isso?

8. Quem usa isso?
Todo e qualquer aparelho que consiga
trafegar pelo protocolo HTTP.

9. Serve para...
Acelerar parcerias
Simplificar integração mobile-cloud
Impulsionar a inovação aberta
Integrar aplicações de software
Criar novos negócios

10. Como funciona

11. Como funciona
Uso dos verbos HTTP
(GET, POST, PUT, DELETE)
Verbos HTTP “imitam” o CRUD

12. URL
http://api.seudomi.nio/nome_da_api/recurso

13. URI (recursos)
/owners
/owners/1234/dogs
/dogs/222/owner

14. URI (recursos)
Recursos são coisas, tem nomes
específicos, mesmo que possam ser
tratados como abstrações.
Usar sempre substantivos para os recursos.

15. Padrão
/recurso/identificador/subrecurso

16. Filtragem de dados
Use query string
/dogs?
color=red&state=running&location=park

17. Resposta parcial
Trazer somente alguns campos
/dogs?fields=color,state,location
[delimitado por vírgula]

18. Resposta parcial
Paginação
/owners/1234/dogs?limit=25&offset=50
(recomendado)
/owners/1234/dogs?start=50&count=25

19. Busca
Global
/search?q=John+Smith
Por recurso
/owners/1234/dogs?q=pluto

20. Modelo de Maturidade de Richardson
RMM

21. RMM
Nivel 0: nada implementado
Nivel 1: uso de recursos
Nivel 2: uso dos verbos HTTP corretamente
Nivel 3: Hipermídia

22. Respostas
O uso dos verbos aliado ao bom uso das
respostas do protocolo HTTP deixam a API
mais poderosa.

23. Respostas
- Tudo que envolva sucesso (HTTP 200)
- O que a aplicação diz que é erro : erro
do cliente (HTTP 400)
- Erros do servidor (HTTP 500)

24. Respostas
Exceções devem ser representadas pelos
códigos de erro corretos;
A mensagem de erro deve ser explicativa;

25. Respostas
Recomenda-se o uso de um código
específico para cada erro da aplicação;
Em desenvolvimento é recomendável
retornar link para a documentação.

26. Exemplo
{
"developerMessage" : "Mensagem bem
explicativa.",
"userMessage":"Mensagem de erro simples.",
"errorCode" : 12345,
"more info":
"http://dev.teachdogrest.com/errors/12345"
}

27. Media Types

28. Request
Accept: application/json
Response
Content-type: application/json

29. Versionamento

30. Versão explícita na URI
/v1/dogs/1234/owner

31. Recomenda-se manter até duas versões de
uma API.
A versão anterior deve ser
mantida por cerca de 6 meses.

32. Segurança

33. Autenticação por token
(geralmente oauth2)

34. Documentação
Dependendo do tamanho da API ou da
quantidade de usuários que ela tenha,
passa a ser interessante ter um site
especializado nela.

35. Documentação
descrição dos endpoints
(parametros de entrada e saida)
exemplos de código
páginas introdutórias
como credenciar aplicações e gerar tokens

36. Documentação
descrição dos endpoints
(parametros de entrada e saida)
exemplos de código
páginas introdutórias
como credenciar aplicações e gerar tokens

37. Documentação
acesso ao suporte
Fórum
Sandbox
self-service signup
(autocredenciamento de apis abertas)

38. Obrigado

39. Perguntas?

40. WWW.EVALDOBARBOSA.COM.BR
br.linkedin.com/in/evaldobarbosa
github.com/evaldobarbosa
twitter.com/evaldobarbosa