Antes de iniciar o desenvolvimento da sua aplicação, conheça os padrões de modelagem das APIs. Depois, 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 se trata de um conjunto de padrões de programação que permite a construção de aplicativos. As APIs são muito utilizadas para realizar a integração entre sistemas diferentes, permitindo que se conectem mutualmente para obter ou enviar informações. Veja alguns exemplos:


  • Pode ser utilizada por um aplicativo para se conectar ao relógio do Windows para utilizar informações de data e hora do computador; 
  • Por aplicativos que se conectam ao Google Maps® para localizar e demonstrar endereços; 
  • Por sites de pesquisa de preços, como o Buscapé®, que consultam informações em diversas lojas para apresentá-las no resultado da pesquisa; 
  • Quando uma empresa faz uma venda pelo cartão, o sistema da administradora se conecta ao sistema da instituição financeira para obter autorização para a transação.

    Tudo isso é realizado através 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.
Exemplo:

https://seuservidordaAPI.com.br/api/clientes

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:

CRUDMétodos HTTP
CreatePOST
ReadGET
UpdatePUT
DeleteDELETE


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:

RecursosGETPOST
/clientes*Cria um cliente
/produtosLista com todos os produtos cadastrados*
/produtos/00A0000001Lista 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 e é mais simples e mais leve que o XML. Por padrão, toda a API trafega JSON, tanto para receber informações (métodos POST e PUT) quanto no retorno (método GET). Devido a essa padronização, para as chamadas POST e PUT é necessário informar o HTTP Header "content-type:application/json". Do contrário, você receberá um erro "HTTP 415: Unsupported Media Type"