APIs REST - Dicas básicas e boas práticas - III

Hoje vamos continuar a apresentação de dicas básicas e das principais boas práticas que podemos usar para criar e usar APIs Restful, ou seja, aderentes ao estilo REST.

Continuando a segunda parte do artigo vamos continuar com algumas dicas de boas práticas para as API Restful.

O tratamento de erros na API

A regra geral no tratamento de erros nas APIs REST é sempre suprir o usuário da API  com informações precisas sobre a ocorrência de forma que ele tenha todas as condições de entender o que aconteceu e do que pode fazer para contornar ou resolver o erro.

Como exemplo veja a resposta para um erro em uma das APIs do Facebook : https://graph.facebook.com/me/photos

Temos :

Faltou apenas informar o status code que fica implícito ser um bad request.

O importante é não deixar o usuário da API perdido sem saber a causa do erro.

O versionamento da API

Como todo o produto de software as APIs também ficam desatualizadas ao longo do tempo e novos recursos deverão ser implementados criando assim uma nova versão da API.

Você deve ter em mente que ao publicar uma API e expor os serviços aos clientes você deverá ter muito cuidado ao atualizar a API pois se incluir novos recursos e desabilitar os recursos antigos pode deixar alguns dos clientes sem acesso ao serviço.

Assim toda atualização de uma API deve ser feita criando uma nova versão e mantendo uma versão anterior com um aviso aos clientes de que ela será desativada em um certo tempo e que deverão migrar para a nova versão.

Assim para criar uma versão da API, uma das abordagens é prefixar o endpoint com a versão da API :

https://api.exemplo.com/v1/produtos/2/

Aqui v1 indica a versão da API. Assim uma outra versão poderá ser identificada como:

https://api.exemplo.com/v2/produtos/2/

Dessa forma, sempre podemos incrementar nosso número de versão da API (por exemplo, v2, v3 ...) sempre que houver alterações significativas em nossa API. Isso também indica aos usuários que algo drástico mudou e eles devem ter cuidado ao usar a nova versão.

Abaixo veja um exemplo de implementação feito na Web API ASP .NET Core:

    [Route("api/[controller]")]
    [ApiController]
    public class ValuesController : ControllerBase
    {
        [HttpGet("v1")]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "value1", "value2" };
        }
        [HttpGet("v2")]
        public ActionResult<IEnumerable<string>> Get()
        {
            return new string[] { "novo value1", "novo value2" };
        }
    ....
}

Aqui os métodos são iguais mas possuem um roteamento diferente que atua como um versionamento do método que possui duas versões v1 e v2 definidas em HttpGet.

A segurança da API

Manter a segurança é importante ao contar com uma API REST, mas existem várias maneiras de autenticar a identidade de um usuário e permitir que eles acessem um endpoint da.

Embora seja possível criar uma API RESTful aberta ao público, a prática recomendada é restringir totalmente o acesso apenas aos usuários apropriados para cada endpoint da API.

Veremos a seguir os principais métodos usados para segurança da API:

Usando certificados de terceiros

Com o uso de certificados de segurança de terceiros, você pode verificar se o servidor ou servidores conectados à sua API são seguros. Esse método é mais indicado quando você tem um conjunto predefinido de servidores que acessam sua API sendo uma opção extremamente confiável.

Autenticação básica HTTP através de contas

Este método usa o nome de usuário e senha padrão. O usuário fornecerá um nome de usuário e senha predefinidos com sua solicitação e você os autenticará com base nessa combinação. Esse método é comumente usado quando você deseja conceder a um usuário acesso direto aos dados por meio de uma conta, sem precisar incluir etapas adicionais.

Autenticação por meio de uma chave de API

È parecido com à autenticação básica, mas nessa situação, você gera uma sequência de caracteres para usar como chave, que é fornecida ao usuário para que ele possa acessar a API.

Esse método também permite que o usuário armazene a chave da API em um arquivo de configuração sem expor seu nome de usuário e senha a qualquer pessoa que tenha acesso a esses dados de configuração. Se a chave da API for comprometida, basta invalidar a chave e seu nome de usuário e senha permanecerem inalterados.

Autenticação por meio de um Java Web Token (JWT)

Esse método depende de um conjunto padronizado de dados a serem fornecidos como um token com suas solicitações de API. Existem três partes nos dados:

  1. Um cabeçalho;
  2. Uma carga útil;
  3. Uma assinatura, todos dados JSON codificados em base64;

O token da web é fornecido com a solicitação da API, o que significa que você pode criptografar novamente o cabeçalho e a carga útil com a chave secreta para garantir que ele corresponda à assinatura. Se a assinatura corresponder, você saberá que os dados foram assinados com a chave secreta que você forneceu anteriormente e podem ser confiáveis.

Nesse ponto, você pode usar as informações de autenticação e autorização fornecidas na parte da carga útil do token da web Java para identificar o usuário sem precisar procurá-lo ou ter dados confidenciais incluídos no token.

Autenticação via oAuth

Nesse método, o usuário deve primeiro ser enviado ao seu site para lidar com a autenticação. O usuário fará login na conta dele no site (além de indicar quais dados eles estão autorizando a API a acessar); nesse momento, você enviará o usuário de volta ao site externo com um token associado à autorização no seu site.

Agora, o usuário pode fornecer o token nas requisições da API para o seu site para verificar quem é o usuário e quais dados sua API pode acessar.

Esses são alguns dos principais meios usados para garantir a segurança da sua API.

Até o próximo artigo.

"E, se não há ressurreição de mortos, também Cristo não ressuscitou.
E, se Cristo não ressuscitou, logo é vã a nossa pregação, e também é vã a vossa fé."
1 Coríntios 15:13,14

Referências:

José Carlos Macoratti