Creating, Editing and Deleting APIs

Creating an API

To add a new API manually, click the + Create API button located in the upper right corner of the API Catalog screen. A menu will open with the following options for creating APIs:

Create API: allows you to create a REST API from the API Management interface by entering all the data manually.
Create Identity: you can create an API Identity by inserting the data manually.
Create GraphQL: you can create a GraphQL API by inserting the data manually.
Import an API: allows you to create an API by importing a documentation file in JSON or YAML format. See more about the import and accepted specification versions below.
Create API with AI: create a new REST API with the help of artificial intelligence. Check out the complete guide for this option.

To have the Create API with AI option available in your environment, request its activation from the product team through the support channel.

When clicking on Create API, you will need to select, in the modal window that opens, which specification the API should follow: Swagger 2.0 or OpenAPI 3.0. The selected specification version will be maintained internally by the system.

After choosing one of the options listed above, the registration screen will be displayed, and the required fields must be filled (with the exception of importing a Swagger file; in this case, the API is created with all required fields, which can be edited later).

The fields API Name and Description do not accept the characters '<' and/or '>'.
What you include in the field Base path will form part of the API’s URL (which will be complemented by the inbound address and environment the API is deployed to).

Other than letters and numbers, these are the accepted characters for the path:

Outside of curly brackets: ! @ $ & ( ) - _ = ' ; : ~ +
Inside curly brackets (as path parameter): - _

If there are environments set up in the Environments page, the option Deployable Environments will be displayed. Otherwise, you might add it later, so it’s not a requirement at this point.

Learn more about Environments.

The option Access token expires in determines the token expiration period for a specific API. In case the field is left empty, the default time of 3600 seconds will be applied.

The Context field is related to the visibility of your API, which will be displayed only to authorised users. These are the options:

Organization: the API will be visible to all users on the system;
Teams: the API will also be visible to the users who are members of the selected team.

Learn more about the creation of teams with Access Control;
Only me: the API will be available only to its original author;
Add users: the API will be visible to specific users:

All users available in the API Manager will be displayed. To alter the permission of a specific user, select the user and choose between Can view or Can edit.

Although the Can edit option grants permission to edit API information, this permission doesn’t go beyond the access rules defined in the configurations of the user’s roles.

To configure the visibility options of your API correctly, users and teams need to be registered. Check the documentation for Access Control to learn more about the creation of users and roles.

The Private API option, when marked, doesn’t allow the API to be accessible for consumption on the Developer Portal.

When clicking Save and next, the basic data of API will be saved. The next two steps (Resources and Flows) are not mandatory (if you import a Swagger file, though, the resources data will be already filled out for you). For more details, access the sections on Resources and Flows.

The last step to create an API is the Publish screen:

This screen allows the API to be deployed, provided the Environments option has been selected in the beginning of the API creation. It is also possible to create test templates, which generate a plan and an app to be linked to the API you are creating. This option will enable the immediate use of your API.

All registered APIs are displayed in cards.

Editing or deleting an API

To access the API edition and deletion screen, click the card. You will be redirected to the Overview screen, where data can be edited by clicking the Edit button. On the bottom right corner, you can click Delete to remove the API.

Read more information about the Overview screen.

Importing APIs

You can create APIs from importing documentation files that follow the OpenAPI specification. The accepted versions of the specification are: Swagger 2.0 or OpenAPI 3.0.

To do this, hover the cursor over the + button in the bottom right corner of the API Catalog screen (accessible from the API Design menu) and click on the option Import an API. The following modal window will open:

Enter a name and version for the API that will be created and click Select file to choose a file from your machine to import. Accepted formats are JSON and YAML.

The original specification version of the imported documentation will be kept internally by the system.

Guidelines for using the OpenAPI 3.0 specification

servers field

The OpenAPI 3.0 specification includes the servers field, which defines the base URLs of the API and indicates where requests should be sent. It specifies the environments (production, staging, development, etc.) where the API is available and contains two subfields:

Field name Type Description

Field name	Type	Description
url (required)	string	Defines the complete URL of the API.
description (optional)	string	Describes the name of the environment specified by the URL. The `description` field will be used by Developer Portal to indicate in which environments the API is deployed.

url (required)

string

Defines the complete URL of the API.

description (optional)

string

Describes the name of the environment specified by the URL. The description field will be used by Developer Portal to indicate in which environments the API is deployed.

Example:

servers:
  - url: https://api.example.com/v1
    description: Production environment
  - url: https://sandbox.example.com/v1
    description: Test environment

Rules for the url field
1. Requirement of basePath when creating the API
  - Even if you do not wish to provide the complete URL, it is necessary to provide at least the basePath (e.g., /v1, /api). In this case, the API will be created but will not be deployed.
2. Complete URL for automatic deployment
  - If you provide the complete URL (e.g., example.com), the API will be automatically created and deployed in the corresponding environment.
3. Restriction on mixing relative and complete URLs
  - It is not allowed to combine relative URLs (basePath) and complete URLs in the same servers block. If this occurs, the following error message will be displayed:
    
    Error: Mixing relative and absolute URLs in the servers field is not allowed.
Rules for the description field

The description field is not required and is not validated during import. However, it follows these behavioral rules:

When the inserted URL is incomplete (only with the basePath) and the description field is filled with the value XXX or left empty
- The API will be created without validating this field, meaning any value entered in it will be ignored.
- When the API is deployed, the value of the description field will be replaced by the name of the deployment environment.
When the inserted URL is complete and the description field is filled with the value XXX or left empty
- The API will be automatically deployed in the environment corresponding to the provided URL.
- The description field will be filled with the environment name according to the provided URL.

Examples

Without complete URL (required to provide the basePath):
```
servers:
  - url: /v1
    description: Production
```

With complete URL (automatic deployment):

servers:
  - url: https://api.example.com/v1
    description: Production

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]