Skip to content

Add a Connect RPC

  1. Add the request, response, validation rules, and service method under proto/scribe/v1.
  2. Add the protobuf scribe.v1.options.v1.authz method option. This is the runtime and generated OpenAPI source of truth. Use allow_anonymous only for intentionally public operations and session_only for browser account or workspace administration that must reject API keys and external JWTs.
  3. Assign any operation larger than the 4 MiB default to an explicit request class in internal/server/request_limits.go and add a boundary test.
  4. Run make generate; never hand-edit generated clients or handlers.
  5. Implement an application use case rather than embedding orchestration in the transport handler.
  6. Normalize errors to Connect codes and avoid leaking provider/database text.
  7. Add handler, policy, and generated-client tests. Generation fails if the RPC is absent from OpenAPI or its authorization descriptor is missing.
  8. Update the API guide. docs/api/scribe.openapi.yaml is generated by Buf.

No new REST business endpoint should be added. Public IIIF resources and OAuth callbacks remain HTTP representations where that protocol requires them.