Introdução às APIs: um guia básico para entender e utilizar as APIs em engenharia de software

Tem você alguma vez se perguntado como você pode acessar suas aplicações favoritas, como Facebook, Hashnode, dev.to, LinkedIn e muitas outras? Sei que consegui pegar sua atenção e você começou a pensar rápido. Ou você imaginou quão fácil era acessar o App de avião WakaNow e obter as passagens mais baratas e acessíveis de todo o mundo? Até os amantes do futebol não são deixados de lado, pois eles podem acessar as pontuações em tempo real.

A resposta para todas essas perguntas é que eles se comunicam com outros sistemas para obter esses dados ou para verificar detalhes, e a modalidade de comunicação é através de uma API.

Neste artigo, o conceito de API será desmystificado e uma compreensão clara e apropriada do que são APIs, seus tipos e sua maneira de operar será aprendida.

Uma API, que significa Interface de Programação de Aplicações, é simplesmente uma ferramenta pela qual sistemas ou tecnologias se comunicam entre si, trocando informação ou dados. Pode ser explicada ainda como uma camada pela qual sistemas se comunicam uns com os outros, seguindo um protocolo ou padrão pelo qual a troca acontece.

As APIs são importantes porque permite que sistemas e tecnologias interajam entre si, compartilhem dados e funcionalidades, e trabalhem juntos para criar sistemas poderosos e eficientes. Além disso, as APIs dão aos desenvolvedores a super habilidade de juntar aplicações para executar uma tarefa específica. Por exemplo, um blog de moda e integrar Flutterwave API para permitir que os clientes pagam por designs ou seminários, você também pode usar sua conta Google para logar em qualquer aplicação vinculada a ela.

As APIs podem ser usadas para obter dados de terceiros e trocar informações, permitindo que fizemos coisas loucas como Engenheiros de Software.

Vamos jogar esta analogia, você quer estudar em uma Universidade. Você deve seguir uma série de processos que envolveria fazer exames e com o resultado, inserir na instituição desejada. Você não precisa ir diretamente ao funcionário de Admissão para uma inscrição, em vez disso, você simplesmente visita o portal deles, inserir seus detalhes e enviar documentos. Enquanto espera pela admissão, uma série de coisas acontecem no backend que você não sabe, mas receberá a admissão se os requisitos forem atendidos.

O processo inteiro é assim, nós queremos se comunicar com o escritório de Admissão da Escola e, já que não podemos acessar o escritório de Admissão diretamente, usamos uma camada de API, que neste cenário é o portal da Escola, que você se referirá como Ponto de extremidade. Cada Ponto de extremidade tem seu próprio protocolo, que é necessário e o resultado esperado. Neste exemplo, o portal da escola está a proteger você de todas as coisas complicadas acontecendo no escritório de admissão.

Imagine que não existisse um portal de inscrição, você teria que ir à Secretaria de Admissões da Universidade para submeter seus detalhes, o que seria demorado e propenso a erros.

Para conectar dois aplicativos de software via internet, um programa, conhecido como o cliente, envia uma solicitação para a API do outro aplicativo. O cliente solicitando recursos da base de dados do aplicativo ou solicitando que uma ação seja executada no servidor.

Após receber e validar a solicitação do cliente, a API executa a ação desejada e retorna uma resposta ao cliente. Esta resposta inclui o status da solicitação (concluída ou rejeitada) bem como quaisquer recursos solicitados pelo cliente.

Fig 1. O funcionamento de uma API

Há cerca de quatro tipos diferentes de APIs, que serão explicados.

Algumas exibições de APIs públicas incluem; Bitquery, Adoptapet, covalenthq.

Uma API privada ou Interna API é um tipo de API que está disponível apenas para os desenvolvedores ou indivíduos que a construíram. Ela só pode ser acessada quando enviada uma convite pelo(s) proprietário(s) para a terceira parte.

Algumas exibições de API privada incluem;

  1. Twilio’s Programmable Voice API

  2. Stripe’s Connect API

  3. Google Maps’ private APIs for enterprise

  4. Salesforce’s Metadata API

  5. API da GitHub Enterprise do GitHub

Uma interface de programação de aplicativos (API) fornecida por uma empresa ou organização para permitir que desenvolvedores externos ou parceiros comunique e interajam com seus serviços, dados ou plataforma é conhecida como API parceira, também conhecida como API de terceiros ou API de desenvolvedor. Estas APIs são projetadas para tornar mais fácil integrar diferentes sistemas, programas ou serviços.

Organizações que desejam expandir a utilidade de seus produtos ou serviços e promoverem a cooperação com desenvolvedores externos ou empresas frequentemente fornecem APIs parceiras. Com a ajuda destas APIs, parceiros podem criar programas, ferramentas ou serviços que fazem uso de dados, funções ou tecnologia da empresa.

Algumas exibições de APIs parceiras incluem;

  1. Twitter API for partners

  2. Spotify for Developers API

  3. API do Dropbox para parceiros

  4. Programa de Desenvolvedores do eBay API

  5. API de Publicidade de Produtos do Amazon

APIs compostos, também chamados de APIs de agregação ou mashup APIs, são tipos de APIs que misturam e agregam informação ou funcionalidade de várias APIs ou serviços subjacentes em uma interface única. Estas APIs simplificam o processo de integração e oferecem uma visão consolidada de várias fontes de dados, permitindo que os desenvolvedores acessem e interajam com diferentes serviços através de uma API única.

Quando programadores precisam receber informações contínuamente ou realizar várias ações a partir de muitas fontes, as APIs compostas são úteis. Uma API composta permite que desenvolvedores enviem uma única solicitação para acessar dados ou realizar ações em vários serviços, em vez de enviar consultas separadas para cada API. O processo de integração é otimizado, a complexidade é reduzida e a eficiência aumenta como resultado.

Aqui está um exemplo de uma API composta que agrega dados meteorológicos de vários fornecedores de serviços meteorológicos:

  1. WeatherAPI

  2. OpenWeatherMap API

  3. Weatherbit API

Para agregar dados meteorológicos desses muitos fornecedores e fornecer aos desenvolvedores um único interface de dados meteorológicos, pode ser criada uma API composta. Isso permite que os desenvolvedores obtenham informações meteorológicas de várias fontes com apenas uma solicitação API.

APIs da Web são as mais comumente usadas porque a maioria das nossas atividades diárias se baseia na Web. As APIs da Web são padrões que permitem que as coisas sejam as mesmas em browsers diferentes. Elas se referem a ambos os lados da comunicação. As APIs da Web, comumente chamadas de Interfaces de Programação de Aplicativos (APIs), são interfaces fornecidas por serviços da Web ou aplicativos que permitem a comunicação e interação online entre eles e outros programas de software. Os desenvolvedores podem acessar de forma programática certas funcionalidades, serviços ou dados de um aplicativo Web ou serviço graças às APIs da Web.

1. APIs RESTful

As APIs RESTful, que significa Transferência de Estado Representacional, é um conjunto de padrões que permite que computadores se comunique uns com os outros pela Web, seguindo os princípios de projeto da arquitetura REST (ou Transferência de Estado Representacional).

Parte de uma API REST Include

  1. Request —–→ Response

  2. Operação – GET, POST, PATCH, UPDATE, DELETE

  3. Ponto de extremidade – Url

  4. Parâmetro/Corpo

  5. Cabeçalhos

Fig 2 Diagrama de uma API REST

Os princípios chave de REST incluem:

  1. Arquitetura Cliente-Servidor: O REST divide os componentes cliente e servidor, permitindo que eles evoluam independentemente. O cliente envia solicitações para o servidor, e o servidor processa essas solicitações e envia respostas de volta.

  2. Sem Estado: O REST é estado-livre, o que significa que cada solicitação do cliente para o servidor deve conter toda a informação necessária para entender e processar a solicitação. O servidor não armazena nenhum contexto do cliente entre solicitações, simplificando a escalabilidade e permitindo melhor cache.

  3. Interface Uniforme: O REST promove um conjunto uniforme de interfaces e operações, normalmente usando métodos HTTP padrão como GET, POST, PUT e DELETE. Cada recurso em um sistema RESTful é identificado de forma única por um URL (Uniform Resource Locator).

  4. Baseado em Recursos: O REST trata de tudo como um recurso, como entidades de dados, serviços ou coleções. Cada recurso tem um identificador único e pode ser acessado e manipulado usando métodos HTTP padrão.

  5. Representação de Recursos: Recursos no REST são representados usando um formato específico, como JSON (JavaScript Object Notation) ou XML (eXtensible Markup Language). O servidor envia representações de recursos de volta ao cliente, que podem incluir dados, metadados ou links de hipermídia.

  6. Interações Estado-Livre: Cada solicitação enviada do cliente para o servidor é autocontínua e não depende de qualquer solicitação anterior ou estado no servidor. Isto permite melhores escalabilidades, pois o servidor não precisa manter informações de sessão do cliente.

Vantagens de uma API REST

  1. Simples e padrão

  2. Escaláveis e sem estado

  3. Alta performance e cacheável

2. APIs SOAP

SOAP, que significa Simple Object Access Protocol, é o serviço web que segue a especificação de serviços web SOAP. É um protocolo de mensagem popular que usa XML como formato, esquema bem definido e protocolo padrão do usuário. É definido pelo World Wide Web Consortium. Os protocolos SOAP cobrem um número amplo de protocolos de comunicação na internet, notavelmente HTTP, SMTP e TCP/IP.

Fig 3 Diagrama de uma API SOAP

Benefícios de usar a API SOAP

  1. Idioma, plataforma e transporte são independentes.

  2. Funciona bem em ambientes empresariais distribuídos.

  3. Oferece extensibilidade significativa pré-construída na forma dos padrões WS*.

  4. Tratamento de erros embutido.

  1. RPC.

O protocolo de chamada de procedimento remoto (RPC) é um meio para enviar vários parâmetros e receber resultados. É uma chamada de função remota, não existe no seu computador local mas é necessário que seja implantado de onde é chamado. É assíncrono em que você precisa obter uma resposta para ser marcado como um sucesso. É uma interação simples entre o Cliente e o servidor. As APIs RPC causam operações operacionais ou procedimentos a serem executados. O RPC pode utilizar duas linguagens diferentes, JSON e XML.

Fig 4 Protocolo RPC

  1. GraphQL APIs

GraphQL é uma linguagem de consulta para APIs que permite que clientes solicitem dados específicos e moldem a resposta de acordo com suas necessidades.

Alguns exemplos de GraphQL APIs

GitHub GraphQL API, Shopify GraphQL API, SpaceX GraphQL API, Yelp GraphQL API, Twitter GraphQL API (Twitter API v2).

Comparando protocolos de API

REST

SOAP

RPC

GraphQL

Funciona com XML, JSON, HTTP e texto simples

Funciona com XML por design

Requer que usuários saibam os nomes de procedimentos

Funciona com HTTP

Funciona bem com dados

Funciona bem com processos (ações)

Parâmetros e ordens específicas

Segurança modesta

Segurança avançada

Documentação pode ser complementada por hipermídia

Mais difícil para desenvolvedores usar

Requer documentação extensiva

Métodos de solicitação são GET, PUT, DELETE, PATCH, UPDATE.

Método de solicitação é POST

Método de solicitação é POST

Método de solicitação é POST

A. Endpoints

Um endpoint de API é um ponto ou fim de uma linha de comunicação. Quando uma API interage com outro sistema, os pontos de contato desta comunicação são chamados de endpoints. Em termos literais, o local onde as APIs envia recursos e onde os recursos saem é chamado de Endpoint. Em APIs, um endpoint é normalmente um uniform resource locator (URL) que fornece a localização de um recurso no servidor.

Exemplo de um Endpoint é

Exemplo de Endpoint da API do Twitter

A API do Twitter expõe dados sobre tweets, mensagens diretas, usuários e mais.

digamos que você quer recuperar o conteúdo de um tweet específico. Para fazer isso, você pode usar o ponto final de busca de tweet, que possui a URL api.twitter.com/2/tweets{id} (onde {id} é o identificador único do tweet).

B. Requisições e Respostas

Uma requisição de API é uma mensagem enviada do Cliente para o servidor. Uma requisição de API é um pedido feito a uma API para acessar ou modificar dados ou executar uma ação específica. Uma resposta de API é o dado ou informação que é retornada em resposta a uma requisição de API.

Por exemplo, um usuário clica neste hiperlink abaixo;

<a href=’http://localhost:2400/categories/01/flavours ’>

Mostrar todos os sabores disponíveis na categoria de sabor

</a>

A mensagem de pedido HTTP será enviada como:

GET /categories/01/flavours HTTP/1.1

Host: localhost:2400

User-Agent: Chrome/5.0 [compatível, Windows 10]

Requisição de API

1. Copiar códigoGET https://api.com/categories/flavours

Resposta da API

1. Copiar códigoHTTP/1.1 200 OK

2. Content-Type: application/json

3.

4. {

5. "id": "01",

6. "flavours": "Chocolate"

7. }

Podemos ver desta requisição que o Endpoint é URL – /categories/01/flavours.

O método de solicitação é GET, a especificação HTTP é 1.1, o domínio é localhost, o porto é 2400, Flavours é o recurso, e o user-agent fornece o navegador e o sistema operacional.

C. Métodos HTTP (GET, POST, PUT, DELETE)

As APIs que utilizam o protocolo HTTP usam métodos de solicitação HTTP (também conhecidos como “verbetes HTTP”) para transmitir solicitações de cliente para servidores. Os métodos de solicitação HTTP mais comumente usados são GET, POST, PUT e DELETE.

  1. GET é usado por um cliente para buscar dados de um servidor,

  2. PUT substitui dados existentes ou cria dados se não existirem,

  3. POST é usado principalmente para criar novos recursos,

  4. PATCH é usado para atualizar parcialmente dados de uma recurso, e

  5. DELETE remove dados ou recursos especificados pelo cliente no servidor.

D. API Segurança – Autenticação e Autorização

Esses dois termos podem soar semelhantes mas têm duas funções separadas. Autenticação se refere à verificação de usuários ou identidade enquanto Autorização se refere ao acesso que um Usuário tem ou permissão concedida para uma ação. Eles são fundamentais para a segurança da API, um método popular para autenticar e autorizar usuários é o OAuth 2.0.

Diferentes tipos de autorização

Existem vários métodos para autorização. As seguintes são diferentes tipos de autorização de API que você pode encontrar:

E. Chaves e Tokens da API

Chaves API são strings de texto que fornecem identificação e autorização de aplicativos clientes. Em outras palavras, elas identificam as aplicações que fazem chamadas ao servidor e determinam se as aplicações que fazem chamadas têm acesso concedido ao servidor API. Elas são usadas para rastrear todas as atividades e bloquear quaisquer comportamentos maliciosos.

A autenticação de chave API foi criada para resolver os defeitos da informação de login compartilhada, que é um grande problema com a autenticação básica HTTP. Ela pode ser usada para dois propósitos. O primeiro passo é identificar o aplicativo cliente que está fazendo uma chamada para sua API de backend. O segundo passo é a autorização do aplicativo cliente, que determina se o aplicativo de chamada tem permissão para chamar a API.

Chaves API são obtidas de fornecedores de chaves API gerenciados em aplicativos web.

Onde armazenar suas chaves API

Nunca embaralhe suas chaves em seu código ou em arquivos porque eles podem ser encontrados publicamente quando você envia para o GitHub, em vez disso, armazene suas chaves API em variáveis de ambiente.

Um exemplo de uma chave API pode parecer como segue.

chave: a9nIbdnaoks97028Jlf.ains9NIKQMEO

Um token de acesso é uma credencial de segurança usada para autenticar e autorizar o acesso a uma API (Interface de Programação de Aplicativos). Os tokens são simplesmente credenciais únicas para o portador do token que é permitido acessar uma API.

Aqui está um exemplo de um Token JWT (JSON Web Token):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Este é um JWT composto de três partes separadas por pontos: o cabeçalho, o payload e a assinatura. O cabeçalho normalmente contém informações sobre o algoritmo de assinatura usado no token, por exemplo:

{

"alg": "HS256",

"typ": "JWT"

}

O payload contém as reivindicações ou declarações sobre a entidade (usuário, cliente, etc.) e pode incluir informações como o assunto, emitente, tempo de expiração e dados customizados. Por exemplo:

{

"sub": "1234567890",

"name": "John Doe",

"iat": 1516239022

}

A assinatura é criada pegando o cabeçalho codificado, payload e uma chave secreta e aplicando um algoritmo criptográfico, como HMAC-SHA256. A assinatura garante a integridade e a autenticidade do token.

Ao usar este JWT, o cliente inclui-o no cabeçalho de autorização de solicitações de API deste modo:

Autorização: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

O servidor da API pode então verificar a autenticidade do token, verificar a validade e usar a informação contida no payload para autorização e outros propósitos.

Observe que o exemplo de token fornecido aqui é apenas para fins ilustrativos e não deve ser usado em um ambiente de produção.

Tokens e chaves são ambas usadas para autenticação e autorização, no entanto, elas diferem das seguintes formas:

Chaves de API são normalmente usadas para identificação e autenticação de clientes ou aplicações quando visitam uma API. Elas frequentemente assumem a forma de strings aleatórias e longas que servem como credenciais. Tokens, por outro lado, são concedidos a clientes ou usuários autorizados após um processo de autenticação bem-sucedido e servem como prova de autenticação.

Duração de vida: A menos que seja deliberadamente revogada ou roteada pelo fornecedor da API, chaves de API normalmente têm uma duração de vida longa. Tokens, por outro lado, frequentemente têm uma curta duração de vida e uma data de expiração. Dependendo da técnica de autenticação, o cliente deve reautenticar ou usar um token de renovação para obter um novo token quando o antigo expira.

Segurança: Token geralmente oferece melhores recursos de segurança em comparação com as chaves API. Os tokens podem ser projetados para ter escopos ou permissões limitadas, permitindo o controle de acesso com granularidade. Eles também podem ser criptografados, assinados ou conter reivindicações adicionais que fornecem integridade e autenticidade. Isso permite autenticação mais segura e melhor proteção de dados sensíveis.

A. API de Clima

As APIs de clima, ou Interfaces de Programação de Aplicativos, são serviços que fornecem acesso real-time a dados de clima e previsões.

Exemplos incluem

. WeatherAPI.com, Forecast, Meteostat.

B. API de Redes Sociais

As APIs de redes sociais permitem que essas plataformas integrem com outros fornecedores de software e aplicativos.

Exemplos incluem

API de Gateway de Pagamento

A interface tecnológica que permite que desenvolvedores de software incluam serviços de gateway de pagamento em suas aplicações ou sites é chamada de API de gateway de pagamento.

Exemplos incluem

Stripe API. Stripe é um serviço altamente aclamado que permite que vendedores aceitem pagamentos online, Noodlio Pay, Square API, PayPal, Adyen, Paybook, KeyPay, BIPS Fatura (por Coinify).

D. Mapping and Geolocation API

A Geolocation API não mantém nenhuma informação, mas permite que você colecione dados existentes do dispositivo sendo consultado. Ela pode coletar dados de posição de várias fontes, incluindo endereço IP, GPS, WiFi, Bluetooth, RFID, ID GSM/CDMA e entrada humana.

Exemplos incluem Geolocation API, Mapbox API, OpenStreetMap API, MapQuest API, HERE API.

IV. Conclusão e Take Home

Ao longo deste artigo, foi estabelecido o que são APIs, como funcionam, exemplos reais, APISecurity, métodos HTTP e a importância das APIs. Deduziu-se que as API permitem aos engenheiros de software integrar aplicações no que está a ser construído e até melhorá-lo. No decurso da minha investigação e redação, descobri que um grande problema é a segurança das API. Se uma API for hackeada, isso afectará todas as aplicações que se ligam a ela, pelo que eu iria aprofundar a minha investigação sobre a segurança das APIs.

Finalmente, irei lançar outro artigo relacionado com este, uma vez que será sobre a exploração de APIs, o trabalho com APIs em códigos, as melhores práticas de API, o design e o desenvolvimento de APIs.

A. Algumas palavras-chave incluem

API – Application User Interface

RPC – Remote Procedural Call

HTTP – Hypertext Transfer Protocol

B. Próximos passos para uma aprendizagem mais aprofundada

Finalmente, eu vou lançar outro artigo sobre isso, já que será sobre explorar APIs, trabalhando com APIs em códigos, melhores práticas em APIs, design e desenvolvimento de APIs.

Source:
https://nechey.hashnode.dev/introduction-to-apis-a-beginners-guide-to-understanding-and-utilising-apis-in-software-engineering