Começar

Convenções

Como todo endpoint se comporta: o que recebe, o que responde e como diz não.

JSON na ida e na volta

Requisições com corpo mandam JSON; toda resposta é JSON. Os campos são snake_case; datas em RFC 3339, em UTC. O Cloud recusa campos que não conhece — um erro de digitação nunca passa em silêncio.

Mudanças

POST cria algo e responde 201 com ele.
PATCH muda só os campos enviados; o resto fica.
PUT define algo inteiro — os valores de um registro, os apps desligados.
DELETE responde 204, sem corpo — ou { "ok": true } no Settings.

Erros

Uma recusa traz as palavras do próprio Yet — as que os apps mostram — em error:

json

{ "error": "There is an environment with that name already." }

Status	Significa
`400`	A requisição não está certa: falta um campo, ou ele não é como deveria.
`401`	Sem key, ou uma key que o Yet não conhece.
`403`	A pessoa da key não pode fazer isso.
`404`	Isso não existe — ou não é algo que a key possa ver.
`409`	Conflita com o que já existe: um nome em uso, algo ainda em uso.
`5xx`	Do lado do Yet. Tente de novo; para leituras é seguro.

Nomes

Os nomes do Cloud — servidores, runtimes, ambientes, bancos — viram nomes do Kubernetes: letras minúsculas, dígitos e hífens, até 32, começando por letra. O de um ambiente nunca muda; os outros podem mudar.

Ids

As coisas são referidas pelo id, nunca pelo nome: renomear uma não quebra nada que aponte para ela. As fontes de dados do Terraform acham um id pelo nome.