Como criar boas API’s em 10 passos (Resumão)
1. Rota inicial
Começe a url indicando que se trata de uma API: api.seusite.com
2. Declare a versão
api.seusite.com/v4/
api.seusite.com/v1.2/
3. Use todos os métodos
Get para obter dados
Post para enviar dados
Put para atualizar dados
Delete para deletar dados
Em PHP só existe declaradamente o Get e o Post como protocolo de envio e recebimento de dado certo? Só que você pode permitir criar rotas com alias para Delete e Put.
Veja como habilitar o método put e delete no PHP
4. Rotas inteligentes
Segue um exemplo do que estou falando:
get api.seusite.com/v1.2/servicos
get api.seusite.com/v1.2/servico/:id/:chave
post api.seusite.com/v1.2/servico
put api.seusite.com/v1.2/servico
delete api.seusite.com/v1.2/servico
Obs. Eu reajustei essas rotas, uma colaboração por: Matheus Victor! Obrigado! Não faz sentido colocar, atualizar ou deletar na rota porque existe o método de transporte já declarado: put, delete etc.
Para as rotas post, put e delete é possível passar os parâmetros da mesma forma que o post. O delete você pode fazer como o get. A chave do usuário serve para verificar se ele tem acesso para tal atividade.
Evite nomes longos e desnecessários em rotas.
5. Respostas concisas
A sua api precisa conversar, dar respostas ao usuário final, ou ele não tem acesso, ou o que ele busca não existe, ou o usuário não foi encontrado, sempre terá pelo menos uma resposta ao que for enviado, incluindo o tratamento de erros.
6. Criptografia
A sua API vai precisar de tokenização para transitar com os dados. Eu recomendo este artigo aqui:
Não vou me aprofundar mais sobre o assunto porque existem vários tipos de tokens e bibliotecas prontas e disponíveis para você usar ou mesmo em um framework isso já é entregue, quem sabe eu num faço um post só falando sobre tokens.
7. End point em Json
Toda a entrega final de uma api deve ser em Json. Acrescente uma linha de cabeçalho como esta no header da aplicação.
header(“Content-type: application/json; charset=utf-8”);
8. Traga dados prontos e calculados
Procure exibir valores em inteiro pois eu posso precisar deles dessa maneira para implementar com JavaScript em meu sistema e datas em inglês pois a maior parte dos scripts que irão fazer filtro de data funcionam em inglês. Eu colocaria as duas informações data e horas formatados e a data em seu formato original.
A filosofia aqui é que o trabalho seja seu como desenvolvedor da API.
9. Teste sua API
Depois da publicação não tem como voltar atrás, em outras palavras, depois da versão 1.0, tem que vir as posteriores, não adianta querer mecher na versão lançada, publicada e divulgada.
10. Documente bem a sua API
Se você seguiu todos os passos anteriores a sua API está bem estruturada então capricha na documentação ensinando de forma prática como consumí-la usando diversas tecnologias, CURL, PHP, Node, Ruby, Python. Basta se espelhar em alguma documentação por ai que tenha uma estrutura confiante (excessão aqui é o pagseguro que tem uma péssima documentação).
Fui muito sucinto com esse tutorial? Deixe sua opnião aqui em baixo, traga críticas ou uma informação adicional.
Att,
