Este documento resume os principais conceitos de uma API REST. Explica que uma API é uma interface de comunicação entre sistemas que usa URLs, recursos e métodos HTTP. Também descreve os benefícios de ter uma API aberta e como REST segue boas práticas de design como uso adequado de URLs, métodos, códigos de status HTTP e formatos como JSON para representação dos dados.
3. O que é uma API?
- Application Programming Interface
- Uma interface de comunicação entre sistemas
- System calls, por exemplo
- API vs Web API / Web Services
4.
5. Por que ter uma API?
- Expor certos dados e recursos é uma estratégia de negócios e inovação
(Ricardo Peloi).
- Grandes players tem uma API aberta
- Integrar nossa plataforma a terceiros (e-commerce, SaaS)
- Gerar mais mercado e expandir o público-alvo
- Gerar desenvolvimento da plataforma para outros meios
- Organização interna do setor de TI
6. REST APIs
- Representation State Transfer
- estilo arquitetural
- regras e convenções
- Criado por Roy Fielding em sua tese de doutorado em filosofia
- Co-autor do HTTP o/
- REST é guiado pelas boas práticas de uso do HTTP
- Uso adequado dos métodos HTTP, URLs, Headers, etc.
- REST não é só pra API
8. Recurso
- Marco zero: em REST tudo é recurso. Representação!
- Recurso: representação de um objeto virtual
- uma image, uma coisa da vida real, uma coleção de objetos, um cliente….
- Pode ser qualquer coisa. Depende do contexto e do mapeamento
9. URLs
- Identificam os recursos de forma única, através de um determinado caminho
- http://localhost:8080/cervejas
- Devem ser amigáveis, semânticas e convencionalmente no plural
- http://localhost:8080/cervejas - retornam todas as cervejas
- http://localhost:8080/cervejas/2 - retorna a cerveja de identificar único 2
- http://localhost:8080/cervejas - crio uma nova cerveja
- http://localhost:8080/cervejas/2 - atualizo uma cerveja existente, no caso a de ID 2
- Relacionamentos:
- http://localhost:8080/paises/2/cervejas - todas as cervejas do pais de ID 2
- http://localhost:8080/paises/2/cervejas/3/premios - prêmios cerveja de ID 3 do país de ID 2
10. Métodos HTTP
- Existem 7 métodos além do GET
- POST, PUT/PATCH, DELETE, OPTIONS, HEAD, TRACE, CONNECT
- Especificam a ação que queremos tomar em cima de algum recurso
- GET http://localhost:8080/cervejas
- GET http://localhost:8080/cervejas/2
- POST http://localhost:8080/cervejas
- PUT http://localhost:8080/cervejas/2
- DELETE http://localhost:8080/cervejas/2
- HTTP header
- GET /cervejas HTTP/1.1
- Host: localhost:8080
- Accept: text/html
-
11.
12. URLs com filtros e ordenação
- GET usando query string parameters
- /cervejas?pais=alemanha
- /cervejas?ordenar=idade,nome
- Filtros comuns devemos usar alias
- /cervejas/ativas ao invés de /cervejas?status=ativas
- Seleção de campos
- /cervejas?campos=id,nome,status,ano_criacao
- Paginação
- /cervejas?pagina=2&limite=30
13. Códigos de status do HTTP
- Toda requisição feita ao servidor retorna com um código de status.
- 1xx - Informacionais
- 2xx - Códigos de sucesso
- 3xx - Códigos de redirecionamento
- 4xx - Erros causados pelo cliente
- 5xx - Erros originados no servidor
- 200 - ok; 201 - created
- 301 - moved permanently; 303 - See Other
- 401 - Unauthorized; 404 - Not found; 405 - Method not allowed
- 500 - internal server error; 503 - service unavailable