Create a custom API

A custom API is an OpenAPI specification that your custom connector implements when no Banking OS unified API fits your use case. You create it from the generic API template. The build packages the specification with a Helm chart that registers the API in Azure API Management (APIM).

Decide whether you need a custom API

If a Banking OS unified API covers your use case, reuse it and build only a connector. You select the unified API in the connector project by setting api.artifact-id and api.artifact-version. For more information, see Banking OS APIs and API playground. Create a custom API in these cases:

No unified API covers the capability that your connector exposes.
You need an API that only your organization uses.

Prerequisites

Before you begin, make sure you have the following:

Access to your self-service repository with the self-service GitHub team. For more information, see GitHub organization and repository structure.
JDK 21, Maven 3.6 or later, and Git installed.
Maven credentials in ~/.m2/settings.xml: a GitHub personal access token for your organization’s GitHub Packages, and a token for the Backbase Artifactory.

Request the API repository

You request the repository through your self-service repository, in the same way as for a connector. To request the API repository, follow these steps:

In gc-devhub-{installation}-self-service, create a branch.
Add an entry to repositories in self-service.tfvars, as shown in the following example.
Open a pull request to main.
Wait for the Terraform plan comment on the pull request.
After the self-service team approves, merge the pull request.

repositories = {
  "YOUR_PREFIX-customer-onboarding-api" = {
    repository_topics          = ["api", "openapi"]
    default_branch             = "develop"
    enable_branch_protection   = true
    protected_branches         = ["main", "develop", "release/*"]
    require_branch_up_to_date  = true
    required_status_checks     = ["Validate pull request / Verify Maven project"]
    repository_init_from_zip = {
      name    = "grandcentral-generic-api"
      version = "TEMPLATE_VERSION"
    }
    repository_visibility = "private"
  }
}

Set TEMPLATE_VERSION to a published release of grandcentral-generic-api. Release 2.0.9 is one published release. The ZIP files are in the Banking OS accelerators tree. The repository_init_from_zip setting accepts only those ZIP files. Name the repository so it ends in -api. Backbase specifications use the grandcentral- prefix. Use your own prefix so the repository name doesn’t collide with a Backbase repository.

The repository name becomes the artifact ID, the API name, and the spec filename. Changing it later can mean deleting and recreating the repository, so choose a unique, prefixed name before you merge.

Understand what the template provides

The generic API template is the reference implementation (the golden sample) for recommended specification practices and build configuration. On the first commit, provisioning automatically:

Sets the artifactId to the repository name and the version to 0.1.0-SNAPSHOT.
Updates the description, URLs, and CODEOWNERS.
Regenerates the README.md and CHANGELOG.md files.
Renames the specification file to {artifactId}.yaml.

The following table lists the main files in the template:

File or folder	Purpose
`pom.xml`	Maven project that validates and lints the specification and builds the APIM Helm chart. It uses `grandcentral-spec-starter` as parent.
`src/main/resources/YOUR_REPO.yaml`	Your OpenAPI specification. Provisioning renames it to the artifact ID.
`src/main/resources/examples/`	Example payloads for the specification.
`.github/workflows/`	Workflows for the build, the pull request check, and the release.

Edit the specification

Change only the content of the specification file. Don’t edit pom.xml, because provisioning sets its values for you. The template info block identifies the API. The following example shows the block with illustrative values:

openapi: 3.0.4
info:
  version: ${project.version}
  title: Customer onboarding API
  description: Customer onboarding OpenAPI specification
  x-icon: category
  x-api-domain: customer-management
  x-api-service: customer-onboarding

Follow these rules:

version: Keep ${project.version}. The build replaces the placeholder with the Maven project version, so don’t hard-code a version.
x-api-domain and x-api-service: Both are required. Use lowercase values, and use hyphens if needed. These values are path segments. They don’t have to repeat the repository name.

These two fields form the path that callers use to reach your API in APIM: https://api.{runtime}.{installation}.gcservices.io/{x-api-domain}/{x-api-service}/v{major}/{path}. For example, a unified API uses /customer-management/party-reference/v2/parties/{id}. If another API already uses the same path on your APIM instance, override the path. Set the Maven property apim-helm-plugin.path at build time, or the path Helm value at deploy time.

Build and release the API

To build the API locally, run the following command:

mvn clean install

The build validates, lints, and checks the specification with Backbase OpenAPI Tools (BOAT), and produces:

A JAR file with the merged specification.
The merged specification at target/openapi/{artifactId}.yaml.
The APIM Helm chart in target/helm. The chart registers the API in APIM.

The APIM API ID is {artifactId}-{major}, for example grandcentral-generic-api-1. You use this ID later in your product policies. When you release the repository, CI publishes the Helm chart to your installation’s container registry. After the first release, you can enable backward-compatibility checks against the previous version: set old-api.version and remove old-api.skip.

Troubleshoot

If the build or deployment fails, compare your repository with the generic API template first.
If another API already uses your path, override the path as described in Edit the specification.

Next steps

Deploy a custom API and connector: Deploy your connector and publish your API through APIM.
Set up the project: Build the connector that implements this API. Set api.artifact-id to your API artifact.

Pro-code connectors

Connector Studio

Sync Hub

Decide whether you need a custom API

Prerequisites

Request the API repository

Understand what the template provides

Edit the specification

Build and release the API

Troubleshoot

Next steps

​Decide whether you need a custom API

​Prerequisites

​Request the API repository

​Understand what the template provides

​Edit the specification

​Build and release the API

​Troubleshoot

​Next steps

Decide whether you need a custom API

Prerequisites

Request the API repository

Understand what the template provides

Edit the specification

Build and release the API

Troubleshoot

Next steps