Uma API é uma interface de programação para comunicação entre aplicativos ou componentes. As APIs são divididas em privadas e públicas. APIs privadas são usadas dentro de uma empresa se, por exemplo, ela tiver vários produtos de software que se comunicam entre si. APIs públicas podem ser usadas por desenvolvedores terceirizados. É verdade que, em alguns casos, você tem que pagar por isso. Mas então os requisitos do usuário para a qualidade e usabilidade da API também serão maiores.
Quando os serviços de API se tornam públicos, nenhum milagre acontece. O número de usuários não está crescendo e, em geral, você pode esquecer de tornar essa funcionalidade paga (excluímos casos em que o produto é promovido devido ao marketing estar associado à publicidade agressiva).
E se a receita da empresa depende diretamente da API pública, então as apostas são muito altas. Essa ideia é discutida com mais detalhes no livro “Desenvolvimento Contínuo de API. As decisões certas em um cenário tecnológico em mudança ”(Mehdi Medjui, Ronnie Mitra, etc.):
e iremos além ... Os
desenvolvedores podem se concentrar principalmente em obter todas as funcionalidades planejadas implementadas na API. Mas existem requisitos “não funcionais” que muitas vezes não são totalmente atendidos e requerem atenção especial.
Em minha opinião, para todas as APIs, é imperativo que os seguintes requisitos não funcionais sejam atendidos com boa qualidade:
- Segurança
- Documentação
- Validação
- Testando
Segurança
Provavelmente não vale a pena explicar por que a segurança vem em primeiro lugar. Eu identifiquei quatro dos desafios de segurança mais importantes:
- Usando HTTPS com certificados SSL
- Compartilhando recursos de fontes diferentes (CORS)
- Autenticação e tokens da web JSON
- Autorização e privilégios de acesso
* A seguir, restringiremos o contexto para REST e API JSON.
1. Usando HTTPS com certificados SSL
HTTPS usando certificados SSL agora é o padrão de segurança de fato. Para gerar certificados, eu pessoalmente uso o Let's Encrypt , um CA gratuito e automatizado do Internet Security Research Group (ISRG) sem fins lucrativos.
Esses certificados garantem que os dados que vão de sua API para o usuário sejam criptografados.
2. Compartilhamento de recursos de diferentes fontes (CORS)
Para manter as solicitações de outras fontes seguras, os navegadores usam um mecanismo chamado CORS. CORS significa Cross-Origin Resource Sharing, uma tecnologia para compartilhar recursos de diferentes fontes. Embora os navegadores (em virtude da mesma regra de origem) não permitam o acesso a recursos de fontes diferentes, o CORS permite que você ignore essas restrições e, ao mesmo tempo, garanta que o acesso aos recursos seja seguro.
Os agentes de usuário (por exemplo, navegadores), com base nos valores dos cabeçalhos adicionais para CORS na solicitação HTTP, podem fazer solicitações a outras fontes que seriam bloqueadas sem CORS.
Aqui está um exemplo : Uma
página HTML servida por um servidor de http://domain-a.com solicita src em http://domain-b.com/image.jpg .
Muitas páginas carregam recursos como estilos CSS, imagens e scripts de diferentes domínios correspondentes a diferentes CDNs (Content Delivery Networks). A
implementação do CORS para Node.js é bastante popular hoje .
3. Autenticação e JSON Web Tokens (JWT)
Existem várias abordagens para autenticação de usuário de API, mas uma das melhores é usar JWT. Esses tokens são assinados usando vários algoritmos criptográficos.
JSON Web Token é um padrão aberto para a criação de tokens de acesso com base no formato JSON. Normalmente usado para transmitir dados de autenticação em aplicativos cliente-servidor.
Para criar um token, você precisa definir um cabeçalho com informações gerais sobre o token, carga útil, como ID do usuário, função e assim por diante, bem como assinaturas. Em termos simples, JWT é apenas uma string no seguinte formato header.payload.signature.
Quando o cliente efetua logon, o serviço de gerenciamento de identidade fornece o JWT ao cliente. O cliente pode então usar esse token para fazer solicitações de API. A API tem acesso a uma chave pública ou segredo que usa para validar o token.
Para verificação, você pode usar, por exemplo, a biblioteca jsonwebtoken . Abaixo está o código JavaScript:
import jwt from 'jsonwebtoken'
exportar função padrão (req, res, next) {
// req.headers.authorization Bearer token
const token = extractToken (req)
jwt.verify (token, SECRET, {algoritmos: ['HS256']}, (err, decodificado) => {
the if (err) {next (err)}
req.session = Decodificado
next ()
})
}
Mais informações sobre JWT, bibliotecas e linguagens de programação suportadas - JWT.io online .
4. Autorização e privilégios de acesso
A autenticação é importante, mas a autorização é tão importante: um cliente que autenticou e recebeu o JWT tem o privilégio de executar uma solicitação específica?
Para testar isso, usamos um escopo. Ao analisá-lo, o serviço de API determina se essa solicitação do cliente pode ser atendida sem pesquisas de ACL caras.
O escopo é um bloco de texto (geralmente separado por espaços) que descreve os privilégios de acesso de um terminal de API. Ele descreve os recursos e ações que podem ser aplicados a eles. Essa formalização funciona bem para APIs REST / JSON, pois são muito semelhantes na estrutura.
RECURSO: AÇÃO (por exemplo, ARTIGO: WRITE ou ARTICLE: READ, onde ARTICLE é um recurso e READ e WRITE são ações).
Isso permite que os desenvolvedores de API se concentrem em recursos, em vez de funções ou usuários. O serviço de gerenciamento de identidade pode associar funções e usuários a escopos específicos e, em seguida, junto com o JWT, enviar o escopo ao cliente.
Dormir calmamente
Ao desenvolver e implementar APIs, a segurança deve sempre ser um dos requisitos mais importantes. Claro, você pode falar e escrever sobre isso sem parar, mas a implementação competente das quatro tarefas descritas na produção já permitirá que você durma bem.
Documentação
O que poderia ser pior do que a falta de documentação? Documentação desatualizada!
Os desenvolvedores são ambíguos quanto à documentação. Muitos claramente não têm muito amor por este negócio. Seja como for, essa tarefa é muito importante - especialmente quando se trata da API pública. Os desenvolvedores de terceiros devem ser capazes de aprender como usá-lo. Além disso, uma boa documentação o ajudará a treinar novos desenvolvedores que se juntam à sua equipe mais rapidamente.
A documentação da API deve incluir três seções básicas:
- Introdução (README)
- Folha de dados (especificações)
- Exemplos de uso (primeiros passos e outras subseções semelhantes)
1. LEIA-ME
A documentação deve informar sobre para que serve a API, como configurar o ambiente, como testar o serviço, como implantar o projeto. Obviamente, os usuários também precisam saber como e onde relatar dificuldades ou problemas.
Isso está escrito no arquivo README. Este arquivo geralmente também é colocado no repositório, ele fornece aos desenvolvedores um ponto de partida para trabalhar com seu projeto.
O README deve conter:
- Descrição API
- Links para referências técnicas e manuais
- Guia de configuração do desenvolvedor
- Guia do testador
- Guia de implantação
- Gerenciamento de dependências
- Guia do Contribuidor
- Código de Conduta
- Licença
- Obrigado
Seja conciso em seu README; você não precisa explicar todas as nuances, mas fornecer informações suficientes para os desenvolvedores mergulharem em seu projeto.
2. Especificações
Na API REST / JSON, cada terminal é uma função criada para um propósito específico. É importante ter uma documentação técnica que descreva cada terminal, entradas e saídas e como o serviço funciona com diferentes clientes.
Você pode criar sua própria documentação de API baseada em OpenAPI .
É uma especificação e estrutura completa para descrever, criar, consumir e renderizar serviços da Web REST. Seu trabalho é permitir que os sistemas de documentação sincronizem suas atualizações com as mudanças no servidor. Métodos, parâmetros, modelos e outros elementos são integrados ao software do servidor por meio do OpenAPI e são sincronizados com ele o tempo todo.
3. Exemplos de uso
Os usuários da API provavelmente não ficarão satisfeitos se você simplesmente descartar as especificações sobre eles. Eles querem saber como usar sua API em situações específicas e como resolver problemas comuns. A maioria dos usuários em potencial tem problemas e recorrem à API para resolvê-los.
Uma ótima maneira de apresentar sua API aos usuários é criar uma subseção de introdução. Isso ajudará você a entender os casos de uso típicos e usá-los para avaliar os benefícios de sua API.
Tres baleias
A documentação é um componente-chave de qualquer API. Ao escrever a documentação, tenha em mente os três pilares da documentação de API de sucesso - READMEs, especificações e casos de uso. E você (e seus usuários) ficarão felizes!
Data de validade
Um aspecto importante do desenvolvimento de API, a validação de dados, costuma ser esquecido por muitos. A validação é o processo de validação da entrada de fontes externas. Essas fontes podem ser um cliente enviando JSON ou um serviço respondendo à sua solicitação. Essa verificação garantirá que os dados estão exatamente como deveriam ser. Graças a ele, você pode eliminar muitos problemas potenciais. Uma importante tarefa de validação é entender qual formato e faixa de valores os dados de entrada devem ter e como controlá-los.
A melhor estratégia é executar a validação antes que seu serviço execute qualquer manipulação de dados. Quando um cliente envia seus dados para sua API, como e-mail, data e nome, certifique-se de que é realmente um endereço de e-mail, a data está formatada corretamente e a string atende aos requisitos de comprimento. Esta simples verificação tornará seu serviço mais seguro e organizado.
Além disso, ao obter dados de um serviço, de algum tipo de banco de dados ou cache, verifique-o novamente para garantir que o resultado retornado seja o esperado.
Você pode implementar a validação manualmente, mas bibliotecas como Lodash ou Ramda também podem ser usadas para esse propósito .... Eles são ótimos para pequenos objetos de dados. Bibliotecas como Joi , Yup ou Zod funcionam ainda melhor porque permitem que você descreva uma estrutura geral de validação, economizando tempo e esforço. Se você precisa de algo independente de uma linguagem de programação específica, dê uma olhada no Esquema JSON .
Melhor manter isso fora
A validação dificilmente é empolgante, mas pode economizar muito tempo que, de outra forma, seria gasto na solução de problemas e na gravação de scripts de migração de dados. Não cometa o erro de confiar que seu cliente enviará dados não verificados se não quiser que dados inválidos acabem em sua lógica de negócios ou armazenamento.
Reserve algum tempo e providencie a validação de sua entrada. Como diz o ditado, é melhor exagerar do que perder.
Testando
O teste é parte integrante do ciclo de vida do software. Em nosso caso, deve ser percebido como um dos principais requisitos não funcionais. Definir uma estratégia de teste pode ser uma tarefa difícil para qualquer projeto, incluindo uma API de serviço. Sempre tente estar ciente de suas limitações e definir sua estratégia de acordo.
O teste de integração é um dos métodos de teste de API mais eficazes. Sua tarefa é verificar se o aplicativo faz a transição correta de um estado para outro. Em nosso caso, o conjunto de testes de integração deve incluir o teste dos pontos de entrada da API de serviço, bem como maquetes para simular o envio de uma solicitação e o recebimento de uma resposta. É assim que verificamos o principal caso de teste do nosso serviço.
Este método permite que você se concentre apenas na lógica de processamento de dados, sem considerar os serviços internos de back-end ou a lógica de apresentação de dados. A falta de dependências torna a execução do teste mais confiável, mais fácil de automatizar e mais fácil de incorporar em um pipeline de integração contínua.
Para testes de integração, eu uso Tape , Test-server e Fetch-mock . Essas bibliotecas permitem que você execute testes isolados em endpoints da API, indo da solicitação à resposta.
Jogo de imitação
Outros tipos de teste e verificação de tipo também são certamente úteis, com o teste de integração tendo a maior vantagem: é altamente eficiente com menos horas de trabalho gastas escrevendo e mantendo testes. E usar ferramentas como Fetch-mock pode fornecer uma simulação completa de troca de dados.
Não pare aí
Depois de concluir todos os quatro requisitos não funcionais, não pare por aí. Existem mais alguns: monitoramento de aplicativos, registro e gerenciamento de API. Mas em qualquer caso, segurança, documentação, validação e teste devem vir primeiro.
Os servidores em nuvem da Macleod são rápidos e seguros.
Cadastre-se pelo link acima ou clicando no banner e ganhe 10% de desconto no primeiro mês de aluguel de um servidor de qualquer configuração!
