Domain APIs

A Domain API publishes the Dynamic Entities and Dynamic Resource Docs (Dynamic Queries included) of one space under a base path of its own, so that an API built on OBP can be offered without OBP's own URL structure in front of it. A space is a bank, or the system space, whose bank id is SYS.

With the base path carbon-registry/v1 over the system space:

• /carbon-registry/v1/activity answers what /obp/v7.0.0/banks/SYS/dynamic-entities/activity answers, and likewise activity/ACTIVITY_ID, my/activity, public/activity, community/activity and activity/ACTIVITY_ID/access;
• /carbon-registry/v1/registry/summary answers what the Dynamic Resource Doc at /obp/dynamic-endpoint/banks/SYS/dynamic-resource-doc/registry/summary answers;
• /carbon-registry/v1/openapi.yaml and /carbon-registry/v1/openapi.json are its OpenAPI document, with the Domain API's own title, description, version and server, and only its own endpoints.

Hyphens in entity names. A Dynamic Entity name uses underscores, such as technologies_practices_processes, and a hyphen is the more usual word separator in a URL, so under a base path the hyphenated form of an entity name answers too: /carbon-registry/v1/public/technologies-practices-processes answers what /carbon-registry/v1/public/technologies_practices_processes answers. Only the segment that names the entity is read this way: the first one after the base path, or the one after my, public or community. Record ids (which may contain hyphens), access and the paths of Dynamic Resource Docs (such as /registry/activities-query) are passed on as written, and a Dynamic Resource Doc is still tried first. The OpenAPI document lists each entity path once, in the hyphenated form. Request and response JSON keys, Role names and the OBP URLs keep the underscored name, and API Metrics record the OBP URL the call was rewritten to. A new Dynamic Entity name may not contain a hyphen or a space in any API version (OBP-09033), so a hyphen in a URL can only stand for an underscore.

Apart from that, Dynamic Entity names are not renamed: only the part of the URL before them is. The endpoints that create and change definitions stay at their OBP URLs; a Domain API publishes the endpoints that serve and take data. Dynamic Endpoints made from a Swagger file are not published under a Domain API yet.

It only renames. A call under a base path is rewritten to the OBP URL and runs exactly as a call to that URL would: the same authentication, Roles, Consents, rate limits, row-level access and field restrictions, and the same API Metrics. A Domain API gives no access the OBP URL would not give. The one difference in a response is that a Dynamic Entity record response leaves out bank_id, because the base path already fixes the space; the OpenAPI document's examples leave it out too.

Base path and version. The base path is two to five segments of lowercase letters, digits, hyphens and dots, ending with the major version as vN, for example carbon-registry/v1. It may not start with a segment OBP serves itself (such as obp or open-banking), and may not overlap another Domain API's base path. The Domain API's version is its full semantic version, MAJOR.MINOR.PATCH, whose MAJOR is the N of the base path. A compatible change, such as a new optional field or a new Dynamic Query, edits version (or leaves it) and keeps every URL; a breaking change gets a new Domain API with a new base path, for example carbon-registry/v2, which can run alongside the old one while clients move. OBP never changes the version itself. For Dynamic Entities OBP already keeps changes compatible once an entity holds records (only optional properties may be added); a Dynamic Resource Doc can be changed in any way, so keeping its changes compatible is up to its author.

No ambiguous paths. Under a base path the Dynamic Entities and Dynamic Resource Docs of the space share one set of paths, and a Dynamic Entity owns every path that starts with its name. Because a Domain API may be registered over any space at any time, OBP keeps every space unambiguous, with or without a Domain API: creating or changing a Dynamic Resource Doc is refused (OBP-09032) when its path would start with a path variable, with my, public, community, openapi.json or openapi.yaml, or with the name of one of the space's Dynamic Entities in either spelling (a doc at /like-this/summary is refused while the entity like_this exists), or when another doc of the same verb would match a request it matches (/registry/REGISTRY_ID and /registry/summary both match /registry/summary). Creating or renaming a Dynamic Entity is refused when one of the space's Dynamic Resource Docs starts with its name in either spelling, when another of the space's Dynamic Entities has the same name once hyphens are read as underscores (possible only with a name from before hyphens were refused), or when it would be named one of those reserved segments. A space holding an ambiguity from before these rules can't have a Domain API (OBP-09031) until it is resolved. Under a base path a Dynamic Resource Doc is tried first, then a Dynamic Entity; with the rules above, at most one of them can answer a request.

Managing. /obp/v7.0.0/management/banks/BANK_ID/domain-apis creates and lists a space's Domain APIs, and /obp/v7.0.0/management/banks/BANK_ID/domain-apis/DOMAIN_API_ID reads, updates and deletes one. BANK_ID is a bank's id or SYS. The Roles are CanCreateDomainApi, CanGetDomainApis, CanUpdateDomainApi and CanDeleteDomainApi, held at that BANK_ID.

Discovery. A Domain API whose is_publicly_discoverable is true is listed, without logging in, at /obp/v7.0.0/banks/BANK_ID/domain-apis, with its base path, version, title, description, URL and OpenAPI document. /obp/v7.0.0/domain-apis lists them for every space at once. It is false unless set, so a Domain API is only listed publicly on purpose. It only controls that listing: the calls under the base path and the OpenAPI document are served the same either way.

Resource Docs. /obp/v7.0.0/banks/BANK_ID/domain-apis/resource-docs?base_path=BASE_PATH gives the same endpoints as the OpenAPI document as OBP Resource Docs, each at its full published path, for API Explorer and other OBP tools. No login is needed.