Antes de iniciar o desenvolvimento da sua aplicação, conheça os padrões de modelagem das APIs. Navegue pela documentação para conhecer as funcionalidades disponíveis.
API
API (Application Programming Interface) ou, em português, Interface de Programação de Aplicativos, é um conjunto de padrões de programação que permite construir aplicativos. As APIs integram sistemas diferentes, conectando-os para obter ou enviar informações. Veja alguns exemplos:
-
Um aplicativo pode se conectar ao relógio do Windows para usar informações de data e hora do computador.
-
Aplicativos se conectam ao Google Maps® para localizar e mostrar endereços.
-
Sites de pesquisa de preços, como o Buscapé®, consultam diversas lojas para apresentar informações no resultado da pesquisa.
-
Quando uma empresa faz uma venda pelo cartão, o sistema da administradora se conecta ao sistema financeiro para obter autorização da transação.
Tudo isso ocorre por meio do uso de APIs.
Modelagem das APIs
Todos os serviços disponibilizados através da API utilizam a tecnologia REST (Representational State Transfer), uma arquitetura que permite interações com serviços web RestFul que disponibiliza recursos através de sistemas distribuídos, popularmente utilizados via HTTP.
O serviço é formado da seguinte forma: http://hostname/versaoapi/recursoRaiz
Onde:
-
Hostname: Endereço principal do serviço;
-
Versão da API: Versão do serviço que está sendo consumido;
-
Recurso Raiz: Nome do serviço.
No Recurso Raiz, podemos acessar as principais operações do serviço (CRUD), através dos métodos do padrão HTTP, conforme tabela abaixo:
|
CRUD |
Métodos HTTP |
|---|---|
|
Create |
POST |
|
Read |
GET |
|
Update |
PUT |
|
Delete |
DELETE |
Ou seja, no serviço/clientes, do exemplo acima, se fizermos uma operação POST, salvaremos um novo cliente. A tabela abaixo mostra algumas das operações que conseguimos executar sobre determinados serviços:
|
Recursos |
GET |
POST |
|---|---|---|
|
/clientes |
* |
Cria um cliente |
|
/produtos |
Lista com todos os produtos cadastrados |
* |
|
/produtos/00A0000001 |
Lista detalhes do produto com identificador 00A0000001 |
* |
O ' * ' na tabela acima, representa que o método não está disponível, então espera-se o retorno com "ERRO 405 - method not allowed".
HTTP 1.1
O protocolo padrão para comunicação com as APIs é o HTTP versão 1.1. Para mais informações sobre esse protocolo, consulte:
http://www.w3.org/Protocols/rfc2616/rfc2616.html
http://www.ietf.org/rfc/rfc2616.txt
UTF-8
O Charset, padrão para chamadas às APIs é o UTF-8. Para mais informações sobre essa codificação, consulte:
https://tools.ietf.org/html/rfc3629
JSON
JSON (JavaScript Object Notation) é um padrão para descrição de dados para intercâmbio entre sistemas, mais simples e leve que XML. Por padrão, toda API usa JSON para receber informações (métodos POST e PUT) e no retorno (método GET). Por essa padronização, nas chamadas POST e PUT é necessário informar no HTTP Header "content-type:application/json". Caso contrário, receberá erro "HTTP 415: Unsupported Media Type"