O que é uma API, em palavras simples: pedidos, respostas e um exemplo REST

PHP e Programação·· 53 visualizações· 5 min de leitura

A resposta curta: uma API é a forma combinada de um programa pedir coisas a outro. Em vez de uma pessoa abrir uma página e clicar, o seu site envia um pedido a um endereço, com um método que diz o que quer fazer, e recebe uma resposta com um código de estado e, quase sempre, dados em JSON. É assim que uma loja fala com o operador de pagamentos, que um formulário manda um SMS ou que uma automação lê uma folha de cálculo. Este artigo é para quem começa a programar uma integração, ou para quem a encomenda a um programador e quer perceber a conversa.

As peças de um pedido

Peça O que é No exemplo abaixo
Endpoint O endereço de uma coisa dentro da API. Numa API REST, cada coisa (uma encomenda, um cliente, uma mensagem) tem o seu. https://api.example.com/v1/orders/123
Método O verbo: GET lê, POST cria, PUT ou PATCH altera, DELETE apaga. GET para ler a encomenda 123; POST para criar uma nova.
Cabeçalhos Informação sobre o pedido: quem pede (a chave), em que formato envia e em que formato quer a resposta. Authorization, Content-Type, Accept
Corpo Os dados que se enviam ao criar ou alterar. Nas APIs actuais, normalmente em JSON. {"customer": "ana@example.com"}
Código de estado O resultado em três algarismos: 2xx correu bem, 4xx o erro está no pedido, 5xx o erro está do outro lado. 200 OK ao ler; 201 Created ao criar; 401 se a chave estiver errada.
Resposta O que a API devolve: os dados pedidos, ou uma mensagem de erro, normalmente em JSON. A encomenda, com o seu estado.

Um exemplo REST, passo a passo

1 Leia primeiro a documentação do serviço. Ela diz o endereço base (aqui https://api.example.com/v1), como se autentica (aqui uma chave no cabeçalho Authorization) e os limites de utilização. «REST» é só um estilo: cada coisa tem um endereço e o método diz o que fazer com ela.
2 Leia uma encomenda com o curl, no Terminal do cPanel (se a sua conta o tiver) ou no seu computador. O -i mostra o código de estado e os cabeçalhos da resposta: curl -i https://api.example.com/v1/orders/123 \
-H "Authorization: Bearer YOUR_KEY" \
-H "Accept: application/json"
3 Leia a resposta de cima para baixo: primeiro o código, depois os dados. HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "status": "paid", "customer": "ana@example.com"} Se o código não for 2xx, o que vem a seguir é uma mensagem de erro, não os dados que pediu.
4 Crie uma encomenda com POST. Agora há um corpo, e o cabeçalho Content-Type diz que vai em JSON: curl -i -X POST https://api.example.com/v1/orders \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"customer": "ana@example.com", "product": "basic-plan"}' Uma API REST costuma responder 201 Created e devolver a encomenda nova, com o seu identificador.
5 Passe para o código só quando o curl funcionar. Em PHP faz-se o mesmo com o cURL: chamar uma API a partir do PHP e ler o JSON. Se a resposta não se deixa ler, veja o json_decode devolve null.
6 Se a resposta é «recebido» e não o resultado final, a API é assíncrona: o resultado chega depois. Veja síncrono ou assíncrono.
A chave da API é uma palavra-passe. O pedido à API faz-se a partir do servidor (PHP, Node, Python), nunca de JavaScript que corre no navegador do visitante: tudo o que vai para o navegador pode ser lido por quem visita o site. Guarde a chave fora do código, como explicado em variáveis de ambiente e segredos, e se ela aparecer onde não devia, siga uma chave de API ficou exposta.
Muitos serviços têm um ambiente de testes (muitas vezes chamado «sandbox»), com chaves e endereço próprios, onde pode criar encomendas e pagamentos sem dinheiro a sério. Use-o até tudo funcionar, e só depois troque para as chaves de produção.

A sua integração não responde como a documentação diz? Envie-nos o endpoint, o método e o código de estado que recebe (nunca a chave) e vemos se há alguma coisa do lado da hospedagem a bloquear.

Abrir pedido de suporte

VEJA TAMBÉM

Chamar uma API web a partir do PHP com o cURL e ler a resposta em JSON

O json_decode devolve null: como descobrir o que está mal no JSON

Síncrono ou assíncrono: porque a confirmação de um pagamento ou de um SMS chega depois

O que é um webhook, e como testar um com curl

Erro de CORS entre o seu front end e a sua API: como resolver

Uma chave de API ou um token ficou exposto: o que fazer, pela ordem certa

PRODUTO RECOMENDADO

Alojamento de sites com cPanel

Domínio e SSL incluídos, cópias diárias e o painel que já conhece. desde 5.940,00 Kz/mês (plano de 3 anos, com cupão)

Ver planos
Esta resposta foi útil? A sua resposta ajuda-nos a melhorar este artigo.

Artigos Relacionados

PHP e Programação 1.057 Como mudar a versão do PHP Pode escolher em que versão de PHP o seu site corre, das mais antigas às mais recentes, e activar ou desactivar extensõe...
PHP e Programação 688 Que tecnologias correm aqui: PHP, Node, Python, Perl, jogos e os limites «O meu programador pergunta se suportam X.» Esta página responde a isso de uma vez, com nomes e versões - e diz também o...
PHP e Programação 1.438 Ver e ajustar a configuração do PHP: versão por pasta, extensões e phpinfo Mudar a versão do PHP de um site inteiro é fácil e está explicado em como mudar a versão do PHP. Este artigo é o passo s...
PHP e Programação 760 Os limites do PHP: memória, tempo, tamanho de upload e o que falha em silêncio «Não consigo carregar a imagem.» «A importação pára a meio.» «O menu perdeu metade dos itens depois de gravar.» São três...
PHP e Programação 642 Onde está o registo de erros do PHP, como o ler, e os erros que mais aparecem Quando um site parte, há duas maneiras de reagir: adivinhar, ou ler o que o servidor já escreveu. A segunda é mais rápid...
PHP e Programação 40 URL de callback ou URL de retorno: porque o cliente voltar ao site não prova o pagamento A resposta curta: num pagamento online há, normalmente, dois endereços seus que o operador usa. O URL de retorno (return...