Rotas e CRUD

As rotas são os pontos de entrada da sua API. Estão agrupadas por recurso, e pode escrevê-las à mão ou gerá-las a partir de um modelo.

Definir uma rota

Uma rota carrega um método, um caminho, uns parâmetros e umas respostas. O caminho utiliza a sintaxe {{param}} do Restorm: assim que escreve {{id}} no caminho, o parâmetro correspondente aparece; retirá-lo suprime-o.

Os parâmetros

O separador Definição de uma rota enumera os seus parâmetros — os parâmetros de caminho (criados a partir dos placeholders {{param}}) e os parâmetros de consulta / cabeçalho que adiciona com Adicionar um parâmetro. Cada um carrega um nome, uma localização (em), o seu carácter obrigatório, uma descrição e, opcionalmente, um exemplo.

A célula Tipo é um combo: escolha um primitivo (string, integer, number, boolean) ou um dos enums nomeados do design com um só clique. Para os casos mais ricos, escolha Advanced… para abrir uma pequena caixa de diálogo onde pode:

• tornar o parâmetro um array e escolher o seu tipo de elemento (array<string>, …) — um parâmetro de consulta multivalor;
• dar-lhe valores de enum inline (o conjunto permitido, enumerado em chips) quando não está tipado por um enum nomeado;
• Extrair para um enum nomeado — promover esses valores inline a um enum partilhado (ver Modelos e enums).

Um parâmetro também pode estar ligado a uma propriedade de modelo (coluna Ligação de modelo), da qual herda o tipo, ou ser marcado como descontinuado. Cada parâmetro — o seu tipo, o seu enum, a sua descontinuação — reflete-se na documentação gerada e em cada projeção de protocolo.

Gerar o CRUD

A partir dos ajustes de um modelo, Gerar o CRUD cria com um clique um grupo de rotas nomeado segundo o plural do modelo, com seis rotas:

Rota	Método e caminho	Respostas
Listar	GET / (paginado)	200
Recuperar	GET /{{id}}	200 · 404
Criar	POST /	201
Substituir	PUT /{{id}}	200 · 404
Atualizar	PATCH /{{id}}	200 · 404
Eliminar	DELETE /{{id}}	204 · 404

A lista é paginada (deslocamento/offset, 20 elementos por omissão, 100 no máximo). Cada {{id}} é automaticamente ligado ao identificador do modelo.

A caixa de diálogo Gerar o CRUD propõe duas opções:

• Substituir as rotas existentes — para evitar os duplicados se regenerar.
• Proteger as rotas de escrita por autenticação — a criação, a substituição, a atualização e a eliminação exigem então um token (bearer), enquanto as leituras permanecem públicas.

Recorda também que o CRUD é servido em cada protocolo: rotas REST, consultas e mutações GraphQL, métodos gRPC, conjunto de entidades OData e operações SOAP (ver Servir o design como mock).

Gerar as rotas de pesquisa

Para cada propriedade marcada como searchable, Gerar as rotas de pesquisa adiciona um parâmetro de consulta ligado à rota de listagem do modelo (e cria essa rota se ainda não existir).

Autenticação

A autenticação define-se a três níveis: um valor por omissão do design, uma autenticação obrigatória por grupo, e uma substituição por rota (que herda do grupo por omissão). Os modos disponíveis são Nenhum, Bearer (JWT), Chave de API (cabeçalho) e Basic.

As etiquetas

As etiquetas agrupam as rotas para a documentação e a exportação OpenAPI. Vivem em dois níveis: uma rota carrega as suas próprias etiquetas (o seu separador Definição), e um grupo carrega etiquetas partilhadas (os seus ajustes) aplicadas a cada uma das suas rotas. As etiquetas efetivas de uma rota são a união das duas — uma etiqueta comum a todo um grupo põe-se, portanto, preferencialmente uma só vez no grupo. Quando transforma uma API importada num design, uma etiqueta presente em todas as rotas de um grupo é automaticamente elevada ao grupo.

A descontinuação

Uma rota (como uma propriedade ou um parâmetro) pode ser marcada como descontinuada a partir dos seus Ajustes. Uma rota descontinuada aparece esbatida na lista de Rotas e nos clientes gerados, e carrega um aviso de descontinuação no seu separador. O sinalizador propaga-se em cada projeção de protocolo — o deprecated de OpenAPI, a diretiva @deprecated de GraphQL, os descritores SOAP e gRPC, e os metadados OData — para que os consumidores de qualquer protocolo servido a vejam.