Uma API é o contrato que um cliente utiliza para solicitar a execução de uma tarefa a um sistema. Em uma entrevista, esse contrato deve tornar as principais ações do usuário simples e previsíveis — como criar uma nota, recuperá-la, editá-la, excluí-la e compartilhá-la com outra pessoa. Ele também deve evitar ambiguidades problemáticas, como ter dois endpoints diferentes que, na prática, “mais ou menos” atualizam uma nota, mas se comportam de maneira distinta diante da mesma entrada de dados. Vamos ilustrar esse contrato com o exemplo de um aplicativo de notas na sua forma mais simples: um cliente (móvel ou web) que se comunica com um serviço de backend responsável por armazenar as notas em um banco de dados.
Nesse projeto base, o cliente envia uma requisição HTTP para o serviço de API, o serviço de API a valida e aplica as regras do contrato, e o banco de dados armazena os registros de notas para que leituras futuras retornem o mesmo estado. O ponto fundamental é a autonomia de ação (agência). O cliente escolhe o que chamar, o serviço de API decide o que é permitido e o que será gravado, e o banco de dados persiste o resultado para que a próxima requisição possa observá-lo. Esse é o modelo que enfatizaremos mais tarde, quando um único servidor deixar de ser suficiente.
A API funcional mais simples nomeia os recursos de forma clara e associa cada endpoint a uma ação do usuário e a uma estrutura de objeto armazenado. Uma nota é um objeto com id, ownerUserId, title, body e carimbos de data/hora; o compartilhamento adiciona uma regra pela qual outro usuário pode ler ou editar a nota com base em uma permissão. Com isso, um conjunto reduzido de endpoints consegue cobrir o fluxo principal sem a necessidade de inventar verbos extras ou sobrecarregar significados. O mapeamento de cada endpoint para um caminho de leitura ou escrita é o que mantém o contrato legível mesmo sob pressão. Vamos mapear esses endpoints em relação ao serviço base e às operações de leitura e escrita no banco de dados.