O que deve obrigatoriamente estar descrito no contrato de API?

No contrato de API devem estar descritos os seguintes elementos:

• Pontos finais (URL) e métodos HTTP suportados (GET, POST, PUT, DELETE, etc.).
• Formato de pedidos e respostas, incluindo a estrutura de dados, tipos de campos, parâmetros obrigatórios e opcionais.
• Códigos de estado HTTP e seus valores para diferentes cenários (sucesso, erros).
• Requisitos de autenticação e autorização — como o cliente deve se identificar.
• Restrições e limites (limitação de taxa, tamanho máximo do pedido).
• Descrição de erros com exemplos e códigos.

Um contrato bem elaborado permite que clientes e servidores interajam corretamente sem mal-entendidos.