1. Boas prticas no desenvolvimento de uma RESTful API Fernando Camargo Graduando em Engenharia de Computao - UFG Fibonacci Solues geis Java EE, Android, Grails, Node.JS e front-end web Artigos: Construindo uma RESTful API Parte 1 e 2 Java Magazine

2. Boas prticas no desenvolvimento de uma RESTful API Agenda: Introduo ao REST Boas prticas: Versionamento Representao HATEOAS Representao parcial e paginao Erros Segurana Cache 3. Introduo ao REST 4. Websites vs Webservices 5. SOAP Especificao XML maior gasto de rede Complexidade dificuldade para HTML5 e mobile Comunicao entre servidores segurana assumida Sem cache 6. REST Estilo arquitetural Diversos formatos JSON ocupa menos rede Simplicidade clientes magros Comunicao entre cliente e servidor Alto poder de cache HTML5 + mobile ready! 7. Seis regras do REST Interface uniforme Stateless Cachevel Cliente-Servidor Sistema em camadas Cdigo sob demanda (opcional) 8. Interface uniforme Contrato entre cliente e servidor Recursos no lugar de aes URLs identificam recursos Operaes identificadas por HTTP Methods GET /produtos GET /produtos/1 9. Interface uniforme Representaes no lugar de recursos (REpresentational State Transfer REST) Hypermedia Mensagens auto-descritivas 10. Stateless Requisies auto-contidas Sem manuteno de estado do lado do servidor 11. Cachevel Possibilidade de fazer cache dos resultados Melhora na performance 12. Cliente-Servidor Separao de responsabilidades Desenvolvimento independente, respeitando o contrato 13. Sistema em camadas Camadas do servidor invisveis ao cliente Aumento de escalabilidade 14. Cdigo sob demanda (Opcional) Possibilidade de resposta com cdigo executvel 15. HTTP Methods Aes sobre os recursos Podem ser ou no idempotentes 16. HTTP GET Usado para se obter determinado(s) recurso(s) Resposta: representao em formato desejado Idempotente GET /recursos GET /recursos/1 17. HTTP DELETE Usado para deletar recurso(s) OK ou Not Found Idempotente DELETE /recursos/1 18. HTTP HEAD Usado para obter metadados do(s) recurso(s) Resposta: representao com metadados relevantes Idempotente HEAD /recursos HEAD /recursos/1 19. HTTP POST Usado para se criar um recurso (sem especificar ID) ou fazer uma atualizao parcial de um existente Resposta: Created + Location ou OK No idempotente 20. HTTP PUT Usado para se fazer uma atualizao completa (ID na URL) ou criar um recurso (especificando ID) Resposta: OK Idempotente 21. Boas prticas 22. Versionamento Quebra de contrato nova verso Cliente especifica verso invocada Prazos de migrao para verses novas Nmero de verso baixa granularidade (v1, v2, v3, etc) URL vs Content-Type/Accept 23. Versionamento - URL Verso especificada na URL GET api.joincommunity.com.br/v1/palestrantes Accept: application/json POST api.joincommunity.com.br/v1/palestrantes Content-Type: application/json Versionamento da API como um todo 24. Versionamento Content- Type/Accept Verso especificada nos headers. GET api.joincommunity.com.br/palestrantes Accept: application/vnd.palestrante-v1+json POST api.joincommunity.com.br/palestrantes Content-Type: application/vnd.palestrante- v1+json Versionamento de representaes dos recursos 25. Representao Diferentes representaes disponveis: XML vs JSON camelCase em nome dos campos Datas em ISO 8601: yyyy-MM- dd'T'HH:mm:ss.SSS'Z' 26. HATEOAS Hypermedia as the Engine of Application State Recursos identificados por URLs Hypermedia hyperlinks para recursos relacionados { href: api.joincommunity.com.br/palestrantes/1 } 27. Representao parcial Apenas campos necessrios como resposta ao GET Parmetro fields GET api.joincommunity.com.br/palestrantes? fields=nome,email {href:[...], nome:[...], email:[...]} 28. Representao parcial Recursos relacionados representados de forma incompleta por padro Parmetro expand GET api.joincommunity.com.br/palestrantes/1? expand=endereco { href: [...], endereco: {href: [...]} } 29. Paginao Parmetros offset e limit Links para next, first, previous, last, etc. Campo items 30. Paginao { href: [...]/palestrantes, next: {href: [...]/palestrantes?offset=10}, [], items: [ {[]}, {[]}, {[]}, {[]}, {[]}, {[]}, {[]}, {[]}, {[]} ] 31. Erros Status HTTP Cdigo que identifica o erro Mensagem destinada ao usurio final Mensagem destinada ao desenvolvedor URL para documentao 32. Erros 409 Conflict { status: 409, code: 145, message: [], developerMessage: [], moreInfo: [...]/docs/api/errors/145 } 33. Segurana Stateless autenticao por requisio Identificao do usurio atrs de um token Autorizao baseada em recursos e no em URLs OAuth 1.0a e OAuth 2.0 34. Cache Performance e escalabilidade ETag 304 Not Modified GET /palestrantes/1 ETag: 62wsc482nsadf742f7831 Body: {[...]} 35. Cache GET /palestrantes/1 If-None-Match: 62wsc482nsadf742f7831 304 Not Modified ETag: 2tfh892fds982nksaf8932 Body: {[...]} 36. Obrigado! E-mail: fernando.camargo.ti@gmail.com