Create API from Git repository

You can use Git to manage multiple versions of the same API in one repository.

Preconditions

Preparing the Git Repository

Currently, the Git repository must follow these conventions, so that API Control Plane can process it:

• The API must be defined in an Open Proxy Specification file (See OpenProxy Specification for details)

  • This file must be located in the top-level directory and must be named
    open-proxy.yaml, open-proxy.yml or open-proxy.json

• Optionally, you may include an Open API file for documentation. Both Version 2 (Swagger) and Version 3 are supported.

  • The Open API file must be located in the top-level directory and must be named
    open-api.yaml, open-api.yml or open-api.json

• Each version of your API must be tagged in Git. API Control Plane will scan the repository for all git tags and will attempt to import the content for each tag as a distinct API version. The version name in API Control Plane will be equal to the Git tag. It is highly recommended, but not required, that the version name inside each Open Proxy Specification file matches the Git tag at which the file is found. Similarily it is recommended that the API name inside all Open Proxy Specification files in a repository is the same.

  • If you differ from any of these conventions, note that when deploying an API to a gateway, only the content of the Open Proxy Specification file is relevant. E.g. if the API name in API Control Plane differs from the one in the Open Proxy Specification file, the API inside the gateway will be named according to the Open Proxy Specification file.

Adding a Git Credential in API Control Plane

When you create an API from a Git repository, you will be asked for a Git credential. If you haven’t already, you must create the Git credential before starting the API creation process. See Configuration Git Credentials on how to do that.

API Creation Process

• Navigate to “APIs“ in the menu on the left side.

• Select “Create New API“ from the menu in the top right corner.

Open

Admin Portal

• A dialog will open, that will guide you through the API creation process. Make sure to select “Create new API from git”. Enter the url of your Git repository and select one of your Git credentials.

Open

• Click the “Next” button to proceed. The Git repository is now analyzed by API Control Plane and you will see the result of this analysis.

• If the analysis results in one or more error(s), the most likely cause is a wrong repository url or a credential that does not have the permissions necessary to access the repository. You can click “Back” and verify your inputs.

• If no errors have been encountered, you will see a brief summary of what has been found in the repository. You will see how many versions have been found as well as some general warnings, e.g. about Git tags that did not contain any Open Proxy Specification file. Click “Next” to proceed.

• The next step shows more details about each discovered version. It will show the name of each version (which is equal to the Git tag) as well as any warnings or errors that have been found while analyzing the Open Proxy Specification file at that Git tag. Click any version with warnings or errors to expand it and show the specific warning or error messages.
  Important: Versions with errors (which likely result from an invalid Open Proxy Specification) will not be imported in the following step. They are only listed here to inform you about these errors and will not be found in API Control Plane once the API creation process is completed. You can fix these errors, update the Git tag and re-scan the repository at a later time, if you wish.

• Enter the details for the new API. The fields have been prepopulated with the values from one of the Open Proxy Specification files from the repository. You may choose to change some of these values here. E.g. if the display name of the API differs between versions, the prepopulated value may not be the one you want to use in API Control Plane, so you may enter a different one. See APIs for more info about API details.
  One important thing to remember is that these API details are only relevant inside API Control Plane. When you later deploy one of your API versions to a gateway, only the information from the Open Proxy Specification file is used to create the API in the gateway. E.g. if the API name in API Control Plane is different from the one in the Open Proxy Specification file you are deploying, the API in the gateway will be named according to the Open Proxy Specification file.
  Click “Create New API” to actually create the new API and all API versions (with no errors) listed in the previous step.

• The next step will inform you about the successful creation of the API. You can now choose to immediately deploy the API into one or more environments, by clicking “Next” or you can click “Skip” to finish the API Creation process at this point.

• Select one or more environments to which you want to deploy the new API. Note that only environments that support Open Proxy Specification Deployment will be listed here. (See Environment Capabilities)

• In the final step, you will see which environments you have selected and you can choose which API version to deploy into these environments. Click “Deploy and Finish“ to start deploying the API and finish the API creation process. If you want to deploy more than one API version, you can do that later as described in Deploy New Versionarchived.