5 etapas para criar uma API bem-sucedida

É a natureza do desenvolvimento de software. Os desenvolvedores criam software com o usuário final em mente. Parece bem simples, mas às vezes esses usuários também são colegas de desenvolvimento. Eles não precisam de coisas quebradas para eles. Eles nem precisam da simplicidade. Tudo o que eles querem é acesso - uma maneira de integrar seu software ao deles. É aqui que entra uma API (interface de programação de aplicativos). Espero destacar cinco etapas que você pode executar para criar uma API bem-sucedida.

Faça sua lição de casa

Quando se trata de desenvolvimento de software, nenhum de nós quer reinventar a roda. Nesse ponto, quase todas as grandes empresas da Web possuem APIs para seus produtos de software. Estude essas APIs e tente entender as diferentes decisões de design que foram necessárias para criá-las.

Existem muitas tecnologias diferentes por aí, mas a maioria das APIs que você verá usará uma interface RESTful ou SOAP. Se você estiver em dúvida sobre qual interface da API usará, sugiro que adote uma abordagem RESTful usando o protocolo HTTP. É mais simples que o SOAP, atualmente é mais popular e será mais fácil começar ao usar um produto de software baseado na Web.

Ser consistente

Uma das coisas que os desenvolvedores mais apreciam é a consistência. Isso inclui, entre outras coisas, endereçamento, argumentos de entrada, formatos de saída e tratamento de erros.

Ao usar uma abordagem RESTful, existem muitos esquemas de nomeação de URI diferentes. Cada um tem seus apoiadores, então escolha um e fique com ele. O mesmo acontece com a estrutura de entrada e saída. A maioria das APIs suporta o uso de XML e JSON como formatos de entrada e saída. Eu sugeriria apoiar os dois, mas escolhendo um formato padrão.

Para entrada, seus requisitos de entrada devem ser nomeados de forma consistente e devem fazer sentido no contexto da chamada da API que você está fazendo. Para saída, verifique se você está usando layouts comuns de estrutura de dados. Se você estiver agrupando a saída de uma chamada de API em um Tag XML, considere fazer isso com suas outras chamadas.

É uma prática comum incluir algum tipo de sinalizador de status nos dados de saída que você envia de volta ao cliente. Ao usar uma abordagem de API RESTful, isso deve ser feito usando códigos de status HTTP. Por exemplo, se você acabou de processar uma solicitação PUT em um objeto de dados existente, o código de status HTTP incluído em sua resposta variará dependendo do resultado da solicitação.

Em vez de um sinalizador arbitrário que indica o status da chamada, um código de status padrão "200 OK" pode ser usado para indicar que a solicitação foi bem-sucedida, enquanto um código de status "400 Solicitação inválida" pode ser usado para indicar que a solicitação foi malformado. Existem alguns códigos de status HTTP que podem ser usados ​​em diferentes situações.

Use OAuth

A maioria dos produtos de software envolve algum tipo de autenticação de usuário para acessar recursos protegidos para esse usuário. Quando se trata de APIs, fazer com que o cliente colete as credenciais do usuário para enviar ao seu servidor é uma prática recomendada. É aqui que entra o OAuth.

O OAuth oferece muitos benefícios sobre a autenticação de nome de usuário / senha de terceiros. Acima de tudo, o cliente nunca tem acesso às credenciais do usuário. O usuário é redirecionado ao seu servidor quando ele efetua login. Depois que o usuário efetua login no site, ele é redirecionado de volta ao cliente em que o cliente receberá um token de acesso para usar em solicitações futuras de recursos protegidos.

Outro benefício importante do uso do OAuth é a capacidade do usuário de cancelar o acesso do cliente a qualquer momento. Se o usuário decidir que, por qualquer motivo, não quiser mais que o cliente possa acessar recursos protegidos em seu nome, basta acessar a interface que você criou e cancelar o acesso do cliente.

Comece cedo

Uma das coisas mais importantes que você pode fazer para tornar sua API um sucesso é começar cedo. Quando você escreve essa função para criar alguma entrada no seu banco de dados, vá em frente, dedique um tempo extra e escreva uma interface de API para ela.

Escreva boa documentação

Nada mata uma API mais rapidamente do que não ter uma boa documentação. Enquanto alguns desenvolvedores podem pegar uma API mal documentada e descobrir como ela deve funcionar, a maioria não quer.

Você deve documentar todas as chamadas de API disponíveis e categorizar suas chamadas de API pelo tipo de dados em que atuam. Além de documentar os pontos de extremidade para as chamadas de API, você deve definir sistematicamente os argumentos de entrada obrigatórios e opcionais, bem como as estruturas de dados de saída. Os argumentos de entrada devem listar um valor padrão, se houver, e também indicar o formato de dados esperado, como um número ou sequência. Por fim, toda chamada de API deve ter uma lista de condições de erro e códigos de status.

Para completar sua documentação, inclua um ou dois exemplos de cenários comuns de entrada e saída para cada chamada de API.

Desenvolvimento de API: Mantenha as coisas simples

Embora possa parecer que o desenvolvimento de uma API seja um empreendimento complicado, a idéia de uma API em si não é um conceito novo e há uma grande quantidade de documentação disponível sobre cada tópico abordado aqui. Apenas certifique-se de usar boas práticas onde você pode encontrá-las e de fornecer uma interface consistente e bem documentada.