7 dicas para criar melhores APIs REST

Alguns dos erros mais comuns que os programadores cometem ao tentar criar uma API REST são:

• Documentação mal escrita
• Arquitetura indefinida
• Definições de endpoints inconsistentes
• Comunicação pouco clara
• Medidas de segurança fracas

Não vivemos num mundo perfeito. É normal cometer erros. No entanto, antes de se envolver em qualquer projeto, deve tomar todas as precauções e conhecer todos os riscos ou erros que poderá cometer.

A mesma abordagem aplica-se ao nosso caso. É por isso que a nossa equipa lhe vai dar algumas dicas com base na sua experiência pessoal e profissional nos parágrafos seguintes.

Documentar a sua API ajuda-o a si e à sua equipa a compreender melhor o fluxo de dados da aplicação. Inevitavelmente, surgirão problemas ao construir uma API. Questões como atualizações de bibliotecas, versionamento da API ou problemas de segurança farão com que deseje ter escrito a documentação.

Ao gerir isto, também reduz os recursos gastos na integração de novos programadores de software remotos ou internos e aumenta a facilidade com que a equipa realiza atualizações e ações de manutenção. Tente dar-lhes a vantagem de desenvolverem a partir da sua API, mesmo sem compreenderem totalmente as tecnologias que utilizou.

Felizmente, hoje em dia, é muito mais fácil criar documentação. Ferramentas como Apiary, Swagger, Raml e muitas outras ajudam os programadores a gerar documentação num instante. Pode sempre inspirar-se em documentação útil e bem escrita, como The Rust Docs, GitHub Developer Docs, Ruby On Rails Guides, CasperJS ou Moment.js.

Devemos sempre tentar manter a comunicação entre o cliente e o servidor privada.

Os programadores utilizam APIs para construir os seus serviços e transferir dados. Se uma API estiver avariada, exposta ou apresentar violações de dados graves, não será certamente escolhida por nenhum programador.

Tente validar os parâmetros de solicitação desde o início. Implemente verificações de validação e bloqueie todas as solicitações que não passarem nessa validação específica. Inclua validações para tipos de entrada, formatos e comprimento. Aceite apenas determinados métodos HTTP para pontos de extremidade específicos e inclua carimbos de data/hora na sua solicitação, de modo que apenas aquelas feitas dentro de um determinado intervalo de tempo sejam aceites. Isso evita alguns dos ataques de força bruta que possivelmente atingirão os seus servidores.

Pode levar a segurança da sua autenticação um passo mais além, implementando a estrutura de autenticação OAuth 2.0. Com a ajuda de aplicações de terceiros, pode criar um ambiente mais seguro para os seus utilizadores.

Nunca exponha informações confidenciais, como nomes de utilizador, palavras-passe, chaves API, etc., em URLs. Se precisar mesmo de transferir estas informações armazenando-as na URL, serialize-as de forma a que apenas a máquina com a qual precisa de comunicar compreenda os dados recebidos.

A API é como uma ponte entre o servidor e o cliente. É por isso que devemos transferir dados num formato adequado para ambas as partes. Esta escolha influenciará a velocidade e o sucesso dos pedidos.

Alguns dos formatos de dados mais frequentemente utilizados na construção de uma API são os formatos de dados diretos, dados de feed e dados de base de dados.

Os formatos de dados diretos são a melhor opção quando se tenta interagir com outras APIs. Alguns dos mais utilizados são JSON, YAML e XML.

Os formatos de dados de feed são normalmente utilizados para publicar atualizações a partir de servidores ou aplicações web front-end e notificar os utilizadores de que estas alterações foram efetuadas. Como provavelmente já adivinhou, estes formatos são mais frequentemente utilizados em redes sociais, blogs ou plataformas de partilha de vídeos.

Na maioria dos casos, os formatos de dados de bases de dados são utilizados para manipular dados entre diferentes bases de dados ou entre outras aplicações e bases de dados. SQL e CSV são dois dos formatos mais utilizados nesta categoria.

Se a API que você e a sua equipa estão a construir irá devolver grandes quantidades de dados, pode ser uma boa ideia implementar a paginação. Devemos sempre evitar qualquer situação em que o utilizador possa ter a oportunidade de derrubar o serviço.

Recomendamos a utilização de um limite predefinido para os dados devolvidos e parâmetros como limit e offset, tal como isto: /users?limit=30&offset=60.

A paginação também oferece uma excelente oportunidade para ajudar os seus utilizadores a lidar com a fadiga de decisão e elimina a já detestada rolagem infinita.

O processo de versionamento de uma API ajuda os programadores a manter o controlo sobre a aplicação. Nunca se sabe como uma nova atualização afeta a usabilidade de cada utilizador. Tente sempre manter as versões antigas da sua API guardadas, mesmo que a altere completamente.

Vejamos alguns exemplos de como uma API pode ser versionada:

• Coloque o número da versão diretamente no URL da API: api.example.com/v1/users
• Defina cabeçalhos personalizados para incluir o número da versão da API: curl -H “API-version: 1.0” https://api.example.com/users
• Ajuste o cabeçalho «accept» para incluir o número da versão da API: curl -H “Accept: application/vnd.example.v1+json” https://api.example.com/users
• Adicione o número da versão como um parâmetro de consulta: https://api.example.com/users?version=1

As APIs RESTful têm quatro métodos para indicar o que os programadores farão com os dados transmitidos.

Embora possa parecer a coisa mais lógica a fazer, os programadores tendem a utilizar apenas 2 dos métodos HTTP apresentados a seguir. É uma prática recomendada utilizar cada um deles sempre que a situação assim o exigir.

• GET — Utilize este método sempre que precisar de obter um recurso ou uma coleção de recursos.
• POST — Os programadores devem utilizá-lo sempre que precisarem de criar um novo recurso ou uma coleção de recursos.
• PUT — Este método é utilizado para atualizar informações específicas.
• DELETE — É bastante autoexplicativo. Ajuda-nos a eliminar recursos existentes ou a coleção de recursos.

Tal como os programadores preferem utilizar apenas dois dos códigos HTTP anteriormente mencionados, na maioria das vezes, utilizam apenas dois códigos HTTP. Isto pode causar muitas dores de cabeça a si próprios no futuro e a todos os programadores que venham a trabalhar no projeto no futuro.

• 200 OK — Este é o código mais comum com que nos deparamos enquanto programadores. Ou, pelo menos, é o que esperamos. É-nos apresentado sempre que uma operação é executada com sucesso.
• 201 CREATED — O método POST apresentado anteriormente anda de mãos dadas com este código HTTP, uma vez que se destina a alertar o cliente de que o recurso foi criado com sucesso.
• 400 BAD REQUEST — Este é o código HTTP que aparecerá sempre que um pedido não for executado com sucesso.
• 401 UNAUTHORIZED — Se precisarmos de restringir o acesso de um utilizador a uma parte da nossa aplicação, este deve ser o código HTTP que enviamos juntamente com a mensagem de erro.
• 404 NOT FOUND — O código HTTP mais comum em toda a Internet. Mesmo quem não estudou desenvolvimento de software sabe que o código HTTP 404 significa que os recursos não foram encontrados.
• 500 ERRO INTERNO DO SERVIDOR — Deve-se devolver este erro sempre que o servidor não conseguir responder.

Como pode ver, todos os códigos HTTP são bastante autoexplicativos. Utilizar cada um deles quando a situação o exigir pode ajudar a poupar muito tempo a longo prazo.

Todos sabemos como é frustrante quando recebemos um erro e a mensagem é vaga. Não só o serviço não está a funcionar, como agora temos de descobrir de onde vem o problema.

Temos de apresentar as mensagens de erro corretas e o código de erro HTTP mais explícito para eliminar esta confusão.

Por exemplo, se um utilizador quiser criar uma nova conta, mas o e-mail já estiver a ser utilizado na plataforma, devemos devolver um código HTTP 400 com a mensagem «O e-mail já existe». Desta forma, evitamos lidar com um número considerável de pedidos, porque o utilizador saberá qual é o problema e não forçará o registo.

Chegámos ao fim de uma lista completa de dicas. Estas são apenas algumas das técnicas que pode utilizar para criar uma API REST mais segura. É claro que existem muitas outras, mas se utilizar apenas as apresentadas acima, provavelmente estará à frente da maioria das que já foram criadas.

Se, no entanto, não tiver tempo nem paciência para criar uma API para os seus projetos de web scraping, por que não investir em algo já pronto? A nossa equipa esforçou-se por criar uma das APIs de web scraping mais seguras e fáceis de usar. Estes são apenas alguns dos princípios fundamentais que utilizaram para garantir que nunca haverá fugas de dados ou tempo de inatividade da API.

Se quiser experimentar, pode obter 1000 chamadas de API criando uma conta gratuita e testando uma das APIs de web scraping mais bem-sucedidas.

Comece já a sua jornada de web scraping!