Guia 04 - Quando usar Resource, Surface, Action e Capability

Objetivo

Este guia evita o erro mais comum na migracao do primeiro consumidor: misturar os papeis de resource, surface, action e capability.

Resource

Use resource-oriented quando a operacao e parte do contrato canonico do recurso.

Entram aqui:

• GET /{id}
• GET /all
• POST /
• PUT /{id}
• DELETE /{id}
• POST /filter
• PATCH /{id}/profile quando isso ainda for manutencao do recurso

Regra:

• resource define o contrato real
• resource e a fonte da verdade de payload e schema

ResourceIntent

Use @ResourceIntent quando um PATCH continua sendo resource-oriented, mas com semantica propria.

Exemplo:

• PATCH /employees/{id}/profile

Regra:

• continua sendo resource
• o intent nomeia a manutencao parcial
• nao vira workflow so porque tem nome proprio

UiSurface

Use @UiSurface quando a UI precisa descobrir semanticamente uma experiencia sobre uma operacao real.

Entram aqui:

• formulario parcial
• view detalhada
• projecao de leitura

Regra:

• surface nao define payload
• surface aponta para operacao real + schema canonico
• ITEM em /schemas/surfaces e discovery-only sem resourceId; a availability real vem de GET /{resource}/{id}/surfaces

WorkflowAction

Use @WorkflowAction quando a operacao e um comando de negocio explicito.

Entram aqui:

• approve
• reject
• resubmit
• bulk-approve

Regra:

• action nao e CRUD
• action nao e patch de manutencao do recurso
• execucao sempre por endpoint tipado real
• ITEM em /schemas/actions e discovery-only sem resourceId; a availability real vem de GET /{resource}/{id}/actions

Capability

Use GET /{resource}/capabilities ou GET /{resource}/{id}/capabilities quando o cliente precisa de um snapshot agregado do que pode ser feito agora.

O snapshot agrega:

• operacoes canonicas publicadas
• surfaces
• actions

Regra:

• capability nao substitui catalogos dedicados
• capability nao define schema inline
• capability agrega ausencia de surfaces e actions como listas vazias, mas os catalogos dedicados mantem sua propria semantica (surfaces automaticas; actions 404 sem workflow)

Regra pratica de decisao

Pergunta 1: a operacao altera ou le o recurso como parte do contrato principal?

• sim -> resource

Pergunta 2: a operacao ainda e manutencao do recurso, mas parcial ou com UX propria?

• sim -> resource + opcionalmente @ResourceIntent + @UiSurface

Pergunta 3: a operacao e um comando de negocio explicito?

• sim -> @WorkflowAction

Pergunta 4: a UI so precisa saber o que existe ou o que esta disponivel agora?

• catalogo semantico especifico -> surfaces ou actions
• visao agregada -> capabilities

Exemplos rapidos

• PATCH /employees/{id}/profile -> resource + @ResourceIntent + opcionalmente @UiSurface
• POST /employees/{id}/actions/approve -> @WorkflowAction
• GET /employees/{id}/surfaces -> discovery semantico contextual
• GET /employees/{id}/actions -> discovery de workflow contextual
• GET /employees/{id}/capabilities -> snapshot agregado contextual