Resource Doc - Glossary

A Resource Doc is the machine readable definition / description of an OBP Endpoint.

The aim is that as much endpoint definition as possible is defined first within the Resource Doc making the Resource Doc the canonical source of truth about the endpoints structure and behaviour.

In total Resource Docs form the server registry of the API: every Endpoint, static or dynamic, is registered in the running server with its Resource Doc, and that registry is the source of truth about the API surface.

Note that the Resource Docs (like the Glossary) can contain instance variables about the OBP-API instance that is running, so HOSTNAMES and various configuration settings are automatically correct.

An OBP API instance only serves resource docs about endpoints that are actually enabled so any client (e.g. the OBP MCP Server or API Explorer) can use them as a capability discovery channel.

Each Resource Doc includes:

The Operation ID / Scala Partial Function name (the source code / function that runs the endpoint) which uniquely identifies the Endpoint (e.g. getCoreAccountById)
The API version the Endpoint is implemented in
The request verb (GET, POST, PUT, DELETE etc.) and URL path
A summary and a longer description (markdown)
An example request body and a successful response body. These are generated from the actual Scala case classes the Endpoint uses, so field names and types reflect the real implementation rather than separately maintained documentation.
The possible error responses
Tags used to group Endpoints in the API Explorer and filter Resource Docs
The Roles (Entitlements) required to call the Endpoint. Roles declared in the Resource Doc are automatically checked by the framework at runtime.
Connector methods the Endpoint depends on (linking to the related Message Docs)

Because the Resource Doc registry lives inside the running server, it differs from a published OpenAPI file in two important ways:

The arrow of generation points from code to documentation: the Swagger / OpenAPI documents that OBP publishes are generated from the Resource Docs, not maintained alongside the code. This avoids documentation drift.
It covers Endpoints created at runtime: Dynamic Endpoints and the auto-generated CRUD Endpoints for Dynamic Entities get Resource Docs when they are created, so per-bank custom APIs are documented by the same mechanism as the static Endpoints - something a static, pre-published API description cannot do.

Resource Docs are available over the Resource Doc endpoints in OBP format (which includes OBP specific metadata such as Roles, Tags and Connector methods) and in Swagger / OpenAPI format. They can be filtered by tags, functions and API collections.

As mentioned above, Resource Docs power the API Explorer interface and are the natural foundation for programmatic consumers of the API surface: SDK generators, API management tooling and AI assistants (such as Opey and OBP-MCP) that need to discover, select and validate calls to Endpoints.