Web API Basics

Web API - Visão Geral

O que é uma Web API?

• Definição: Uma Web API (Application Programming Interface) é uma interface de programação de aplicativos projetada para ser usada via Internet ou rede. Ela permite a interação entre diferentes sistemas de software, frequentemente utilizando o protocolo HTTP para comunicação.
• As Web APIs expõe funcionalidades sem distribuir código. É ótimo para implementar algoritmos proprietários.
• As Web APIs permitem automação e composição de sistemas.
  • Automação: Web APIs proporcionam a capacidade de automatizar processos e interações entre diferentes sistemas de software.
    • Por exemplo, uma API de gerenciamento de estoque pode automaticamente atualizar os níveis de estoque em um sistema de e-commerce sempre que uma venda ocorre, sem intervenção humana.
  • Composição de Sistemas: Web APIs facilitam a combinação ou integração de funcionalidades de diferentes sistemas para criar novos serviços ou aplicações.
    • Por exemplo, uma aplicação de viagens pode integrar APIs de diferentes companhias aéreas, hotéis e serviços de transporte para oferecer uma solução completa de planejamento de viagens aos seus usuários.
• Exemplo: Uma API de previsão do tempo que fornece dados meteorológicos para aplicativos de terceiros.

API Orientada a Recursos

• Conceito: Uma API orientada a recursos foca na manipulação de "recursos" (entidades ou objetos) através de uma interface padronizada.
• Recurso: um “recurso” refere-se a qualquer entidade ou conceito que possa ser identificado, manipulado e interagido através da API. Um recurso é tipicamente representado por um objeto de dados e tem um identificador único, frequentemente expresso como uma URL. Os recursos são os elementos fundamentais em APIs orientadas a recursos, e cada um deles é endereçado e manipulado através de requisições HTTP.
• Características:
  • Recursos Identificáveis: Cada recurso é identificado por um URI (Uniform Resource Identifier).
  • Operações Padronizadas: Utiliza métodos HTTP padrão (GET, POST, PUT, DELETE) para realizar operações CRUD (Create, Read, Update, Delete) em recursos.
  • Stateless: Cada requisição é independente, e o estado não é mantido entre as requisições.
• Exemplo: Uma API de gerenciamento de usuários onde cada usuário é um recurso, acessível via URI e manipulável através de métodos HTTP.

RPC (Remote Procedure Call)

• Definição: RPC é um protocolo que permite a execução de uma função em um sistema remoto como se fosse local.
• Funcionamento: Em vez de manipular recursos, o RPC foca em ações e procedimentos.
• Exemplo: Uma API que permite acionar a impressão de um documento em um servidor remoto usando uma chamada de procedimento como printDocument(documentId).

Diferença entre RPC e API Orientada a Recursos

Aqui está uma tabela comparativa destacando as principais diferenças entre RPC (Remote Procedure Call) e APIs Orientadas a Recursos:

Característica	RPC (Remote Procedure Call)	API Orientada a Recursos
Foco Principal	Ações ou funções específicas.	Recursos (como usuários, posts, etc.).
Abordagem	Procedural, com operações nomeadas (como createUser, deletePost).	Declarativa, utilizando métodos HTTP para ações CRUD.
Design	Centrado em operações específicas e muitas vezes únicas.	Centrado em entidades do domínio e suas relações.
URLs	URLs podem refletir ações ou operações específicas.	URLs representam recursos específicos e utilizam métodos HTTP para ações.
Métodos HTTP	Menos ênfase nos métodos HTTP; mais foco na operação chamada.	Utiliza métodos HTTP padronizados (GET, POST, PUT, DELETE) para interagir com recursos.
Escalabilidade	Pode ser menos escalável devido à natureza específica das operações.	Tende a ser mais escalável devido ao uso uniforme de padrões HTTP.
Exemplo de Operação	getUserData(userID) - uma função chamada para obter dados do usuário.	/users/{userID} com método GET para obter dados do usuário.
Intuitividade	Pode ser mais intuitivo para desenvolvedores acostumados com programação procedural.	Pode ser menos intuitivo para operações complexas, mas mais previsível e padronizado.
Utilização Ideal	Eficiente para operações complexas que não se encaixam bem no modelo CRUD.	Eficiente para aplicações onde o modelo CRUD é predominante e os recursos são bem definidos.

Esta tabela visa ilustrar as diferenças conceituais e práticas entre as duas abordagens, ajudando a entender melhor em quais cenários cada uma pode ser mais adequada.

Diferença entre URI e URL

A diferença entre URI (Uniform Resource Identifier) e URL (Uniform Resource Locator) é fundamental para entender como os recursos na internet são identificados e acessados:

1. URI (Uniform Resource Identifier):

   • Definição: Uma string de caracteres usada para identificar um recurso na internet ou em uma rede.
   • Propósito: Identificar um recurso, que pode ser qualquer coisa, incluindo documentos, imagens, serviços, etc.
   • Exemplo: https://example.com/page, mailto:user@example.com
   • Características:
     • Pode ser uma URL ou URN (Uniform Resource Name).
     • Representa tanto a localização do recurso quanto o nome ou ambos.

2. URL (Uniform Resource Locator):

   • Definição: Um tipo específico de URI que, além de identificar um recurso, fornece um meio de localizá-lo ou acessá-lo.
   • Propósito: Localizar um recurso na internet, especificando o seu mecanismo de acesso (protocolo) e localização (endereço).
   • Exemplo: https://example.com/page
   • Características:
     • É uma forma concreta de URI.
     • Inclui um esquema (como http, https, ftp) seguido pelo endereço do recurso.

Em resumo, toda URL é uma URI, mas nem toda URI é uma URL.

A URI é um termo mais abrangente que pode se referir tanto a URLs (que localizam recursos) quanto a URNs (que nomeiam recursos sem especificar onde estão localizados).

Vou enriquecer a descrição das características de uma boa API, adicionando exemplos para cada uma delas:

---

Características de uma Boa API

1. Operacionalidade

• Descrição: Funciona conforme esperado, atendendo a requisitos funcionais e não funcionais.
• Exemplo: Uma API de geolocalização que fornece coordenadas precisas e confiáveis, e é capaz de lidar com um grande número de solicitações simultâneas, demonstrando boa performance e confiabilidade.

2. Expressividade

• Descrição: Facilita para os usuários expressarem o que desejam fazer.
• Exemplo: Uma API de gerenciamento de tarefas que permite aos usuários criar, atualizar, excluir e pesquisar tarefas com comandos claros e intuitivos, como createTask, updateTask, deleteTask, e searchTasks.

3. Simplicidade

• Descrição: Fácil para casos comuns, com opções para casos mais complexos.
• Exemplo: Uma API de processamento de imagens que oferece funcionalidades básicas como redimensionamento e recorte de imagem com métodos simples, mas também suporta operações avançadas como detecção de objetos e manipulação de cores.

4. Previsibilidade

• Descrição: Consistente em forma e comportamento, sem surpresas para o usuário.
• Exemplo: Uma API de serviço de e-mail que mantém a mesma estrutura de resposta para todos os métodos, como enviar e-mail, recuperar e-mails da caixa de entrada e excluir e-mails, fornecendo feedback consistente e previsível para os desenvolvedores.

5. Exemplo Adicional

• Descrição: Uma API que ilustra as características acima.
• Exemplo: Uma API de pagamento que oferece métodos claros para processar pagamentos (processPayment), emitir reembolsos (issueRefund) e verificar transações (checkTransaction). Ela é robusta e confiável (operacional), tem métodos intuitivamente nomeados (expressividade), é fácil de usar para transações padrão, mas também suporta configurações personalizadas para casos complexos (simplicidade), e apresenta uma resposta consistente em todos os métodos (previsibilidade).

Estas características ajudam a garantir que a API seja fácil de usar, compreender e integrar, além de ser eficaz em atender às necessidades dos desenvolvedores e do negócio.