O que é um web service?

Um web service é uma interface pela qual aplicações trocam dados ou acionam funções pela rede. Um site é feito principalmente para pessoas lerem e usarem; um web service expõe um contrato pensado para clientes de software. O mesmo produto pode oferecer as duas coisas. Muitos serviços usam HTTP e JSON, mas o termo também abrange outros protocolos e formatos de dados.

Como funcionam a requisição e a resposta

O cliente envia uma requisição para um endpoint definido, com um método, parâmetros e, quando necessário, credenciais. O serviço valida a requisição, executa a operação e devolve uma resposta. Nas APIs HTTP, os códigos de status distinguem os resultados em linhas gerais: sucesso, um problema do lado do cliente (como uma entrada inválida) ou uma falha do lado do servidor. O corpo da resposta costuma trazer mais detalhes em um formato documentado.

Um contrato claro descreve caminhos, métodos, campos, tipos, autenticação, limites de requisições e condições de erro. É esse contrato que permite desenvolver os clientes de forma independente. O versionamento importa, porque mudar um campo ou a forma de interpretá-lo pode quebrar aplicações existentes mesmo que o endereço do endpoint continue o mesmo. Mantenha a compatibilidade com versões anteriores quando ela tiver sido prometida e divulgue os prazos de descontinuação.

Estilos de interface mais comuns

REST é um estilo de arquitetura, não um formato de transmissão específico. As APIs HTTP chamadas de RESTful geralmente representam recursos por URLs e usam métodos como GET para leitura e POST ou PUT para alterações. Um GET não deve causar mudança de estado duradoura, já que clientes e intermediários podem repeti-lo ou guardá-lo em cache. O SOAP usa mensagens XML estruturadas e descrições formais de serviço, comuns em muitos sistemas corporativos.

O GraphQL permite que o cliente peça uma seleção definida de campos com base em um schema, muitas vezes sobre HTTP. Isso pode reduzir a transferência de dados desnecessários, mas traz complexidade em relação ao custo das consultas, à autorização e ao cache. Os webhooks invertem o padrão habitual de polling: um serviço chama um endpoint registrado quando ocorre um evento. Eles exigem autenticação do remetente, tratamento de novas tentativas e proteção contra entregas duplicadas. Nenhuma dessas abordagens é a melhor em todos os casos.

Segurança e privacidade

Use HTTPS para proteger os dados em trânsito e verifique o certificado do servidor. Autentique quem chama a API com um esquema de credenciais adequado e autorize cada operação e cada objeto separadamente. Um token válido comprova apenas o que o seu escopo permite; ele não torna segura qualquer entrada. Valide o tamanho e os tipos das requisições, evite expor dados privados nas mensagens de erro e defina limites contra abusos.

Segredos não devem aparecer em URLs públicas, no código executado no cliente nem em logs. Revogue e substitua credenciais expostas, restrinja o escopo delas e use credenciais separadas para produção e testes. Em APIs que aceitam uma URL de callback, valide os destinos para impedir requisições a redes internas. Documente quais dados pessoais são retornados e guarde apenas o necessário.

Confiabilidade e desempenho

Redes falham, por isso os clientes precisam de timeouts, de um número limitado de novas tentativas e de um tratamento claro de falhas parciais. Repetir uma leitura é seguro quando não há efeitos colaterais; repetir um pagamento ou outra alteração exige um projeto de idempotência para evitar duplicidades. A paginação limita resultados grandes. O cache pode aliviar a carga com dados públicos estáveis, enquanto respostas privadas ou que mudam rápido exigem uma política de cache cuidadosa.

Os operadores devem medir latência, taxa de erros e disponibilidade a partir do caminho real dos clientes. Um servidor que responde HTTP 200 ainda pode devolver dados incompletos ou inutilizáveis, então monitore também os resultados de negócio esperados. Limites de requisições protegem o serviço, mas devem ser comunicados de forma previsível. Se o serviço for importante para os usuários, ofereça uma página de status ou um canal de suporte para incidentes.

Como escolher ou desenvolver um serviço

Comece pela tarefa do usuário e pelo contrato de dados e, depois, escolha um estilo de interface que os clientes consigam implementar e a equipe consiga manter. Teste respostas normais, entradas malformadas, credenciais expiradas, permissões, paginação e timeouts. Mantenha os exemplos atualizados e mostre erros concretos. Ao integrar um serviço de terceiros, leia os limites de uso, a política de dados e os avisos de mudanças; um endpoint conveniente continua sendo uma dependência que pode falhar.