> ## Documentation Index
> Fetch the complete documentation index at: https://agenticbanking.backbase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom API

> Create an OpenAPI specification repository from the generic API template and prepare it for Azure API Management.

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](/banking-os-apis/overview) and [API playground](/banking-os-apis/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](/platform/platform-administration/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:

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

```hcl theme={"system"}
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](https://repo.backbase.com/ui/native/repo/com/backbase/gc/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.

<Warning>
  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.
</Warning>

## 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:

```yaml theme={"system"}
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:

```bash theme={"system"}
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](#edit-the-specification).

## Next steps

* [Deploy a custom API and connector](/platform/developer-guides/deploy-custom-api-and-connector): Deploy your connector and publish your API through APIM.
* [Set up the project](/platform/developer-guides/build/set-up-the-project): Build the connector that implements this API. Set `api.artifact-id` to your API artifact.