🥇 Regras simples para um design lógico de API RESTful

O trabalho da API é tornar o desenvolvedor o mais bem-sucedido possível.

Esta é uma coleção de alguns princípios simples que considero úteis para obter APIs RESTful sãs e desobstrutivas.

Devo ressaltar que algumas das afirmações que apresentarei são estritamente pessoais , conclusões a que cheguei por meio de minha (limitada) experiência nesta área. Além disso, presumo que a resposta venha em JSON.

Você deve usar os códigos de status HTTP corretos.

Uma boa API deve sempre tentar retornar os códigos de status HTTP apropriados para cada solicitação. Dessa forma, as respostas a solicitações simples (como definir um valor para trueou false) podem ser definidas apenas por códigos de status, sem dados adicionais envolvidos. Verifique os códigos de status aqui .

Todos os campos de resposta devem começar em minúsculas, seguindo a notação camelCase.

Impor uma convenção de nomenclatura clara é fundamental, e esta obedece às convenções JavaScript e é familiar em Java e Objective-C. Então, faça algo assim:

{
    "weatherCondition": "sunny",
    "weatherTempC": "25",
    "weatherTempF": "77"
}

Se um campo não tiver valor, será nulo.

Este é bastante trivial, mas tem algumas nuances. Números, strings e booleanos não existentes são geralmente representados como null. Mas os campos de string sem valor também devem ser representados como null, não "" .

Nota : Matrizes vazias não devem ser null. Se um campo for algum tipo de lista e for representado por um array, um array deve ser retornado, mesmo que vazio. Isso torna o trabalho dos desenvolvedores front-end muito mais fácil.

Exemplo:

{
    "id": 16784,
    "name": "Lorem Ipsum",
    "age": null,
    "relatives": [], // no relatives
    "address": null
}

Um tipo de campo deve ser booleano se seu valor for binário.

Não use 0e 1, não use e e não tente encontrar uma solução melhor. Use o que você tem: e . É universal e objetivo.”0””1”truefalse

Uma resposta deve usar campos de cabeçalho relevantes de HTTP sempre que possível.

Por exemplo, as respostas devem ter um gosto correto .Content-Typeapplication/json

Uma resposta não deve ter uma descrição de serviço / terminal.

Isso é redundante. Você não está rastreando por meio de uma API, não está perguntando “Então, para que serve esta resposta?”

Você sabe o que solicitou e seu ponto final, está ciente do que está esperando e está pronto para isso. Assim, você não precisa de um campo informando qual serviço ou endpoint você alcançou.

Além disso, mantém uma resposta mais limpa, removendo campos supérfluos e encapsulamentos desnecessários. Portanto, certifique-se de não fazer algo assim:

{
    "service": "randomservice:api",
    "response": {
    ... //stuff
    }
}

Agora, algumas preferências pessoais:

Você sempre deve incluir uma série de erros na resposta.
Mesmo que nenhum erro tenha ocorrido, você deve incluir uma série de erros. Uma resposta bem-sucedida é uma ausência de erros, portanto, uma matriz vazia. Ao lidar com a resposta, você primeiro verificará a presença de erros e só depois continuará.
Você deve paginar suas respostas.
Algumas solicitações podem ser muito longas e pesadas, como listagens. E às vezes você não quer a lista completa, apenas algumas partes dela. Portanto, é aconselhável seguir uma estratégia de definição do início e do fim de uma solicitação. Exemplo: irá solicitar os seguintes elementos a partir do elemento de índice. ?limit=30&offset=0300
Você deve fornecer respostas parciais
E se você apenas quiser solicitar atualizações de um campo específico de uma entidade complexa? Não deve haver necessidade de solicitar todas as informações … Portanto, adicionar um especificador de campo é uma boa prática. Algo como isto irá receber apenas o campo solicitado: . ?fields=name,age,weight,