Working with OpenAPI extensions

Use the developer toolkit CLI extensions commands to manage OpenAPI extensions in your Catalogs or Spaces.

You can extend the OpenAPI specification by adding either a JSON or YAML extension schema to an API, depending on the version of IBM® API Connect you are using. An extension is imported into a Catalog, or as Space ion a Catalog, then added to the API schema.

The commands described here are for importing OpenAPI extensions into a Catalog or Space, and viewing and managing them. After you have imported an OpenAPI extension, you can reference it in your API definitions; for details, see Referring to an extension in an API definition.

Note: If Spaces are enabled in a Catalog, an OpenAPI extension that you import into one Space is imported into all Spaces; you cannot import an OpenAPI extension into an individual Space in the Catalog. Any subsequent updates are also applied to all Spaces.
Command name Action Syntax
extensions clear The extensions:clear command deletes all versions of an extension given the extension name.

The parameters are as follows:
--scope
Specifies whether you want to clear the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
--confirm <catalog_name>
Confirms the clear of the extension.
<extension_name>
Specifies the name of the existing extension.
Note: This is the extension name, not the file name.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
apic extensions:clear --scope catalog|space 
--catalog | -c catalog_name
 extension_name 
--server | -s mgt_server_endpoint
--configured-gateway-service gw_service_name 
--confirm catalog_name 
--org | -o org_name 
[--space space]
Example:
apic extensions:clear --scope catalog 
--catalog catalog1 extension1 --server endpoint1 
--configured-gateway-service gw_service1 
--confirm catalog1 --org my_org

This example deletes all versions of the extension1 extension that are in catalog1 of the my_org organization, and are paired with endpoint1.

extensions clear-all The extensions:clear-all command deletes all of the extensions in the specified Catalog or Space.

The parameters are as follows:
--scope
Specifies whether you want to clear the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
--confirm <catalog_name>
Confirms the clear of the extension.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
apic extensions:clear-all --scope catalog|space 
--catalog | -c catalog_name 
--server | -s mgt_server_endpoint 
--configured-gateway-service gw_service_name 
--confirm catalog_name 
--org | -o org_name 
[--space space]
Example:
apic extensions:clear-all --scope catalog 
--catalog catalog1 --server endpoint1 
--configured-gateway-service gw_service1 
--confirm catalog1 --org my_org

This example deletes all the extensions that are in catalog1 of the my_org organization, and are paired with endpoint1.

extensions clone The extensions:clone command creates a local definition file for each extension.

The parameters are as follows:
--scope
Specifies whether you want to clone the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
org
Sets the scope to the organization.
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
apic extensions:clone --scope catalog|space 
--catalog | -c catalog_name 
--org | -o org_name 
[--space space] 
--server | -s mgt_server_endpoint 
--configured-gateway-service gw_service_name
Example:
apic extensions:clone --scope catalog 
--catalog catalog1 --org my_org --server endpoint1 
--configured-gateway-service gw_service_1

This example clones the extensions that are in catalog1 of the my_org organization, and are paired with endpoint1.

extensions create The extensions:create command creates an extension in a Catalog or Space, given an extension definition file.

The parameters are as follows:
--scope
Specifies whether you want to clear the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
<extension_file>
Specifies the name of the extension file that contains the new information for your extension.
Note: This is the OpenAPI file name, not the name of the extension.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
apic extensions:create --scope catalog|space 
extension_file 
--server | -s mgt_server_endpoint 
--catalog | -c catalog_name 
[--space space] 
--org | -o org_name 
--configured-gateway-service gw_service_name
Example:
apic extensions:create --scope catalog filename.yaml 
--server endpoint1 --catalog catalog1 --org my_org 
--configured-gateway-service gw_service_1

This example creates an extension in catalog1 of the my_org organization, paired with endpoint1, using the filename.yaml OpenAPI extension definition file.

extensions delete The extensions:delete command deletes a specific version of an extension.

The parameters are as follows:
--scope
Specifies whether you want to clear the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
<extension_name>:<version_number>
Specifies the name and version number of the extension.
Note: extension_name is the extension name, not the file name.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
apic extensions:delete --scope catalog|space 
extension_name:version_number 
--catalog | -c catalog_name 
--org | -o org_name [--space space]
--server | -s mgt_server_endpoint 
--configured-gateway-service gw_service_name
Example:
apic extensions:delete --scope catalog myextension:1.0.0 
--catalog catalog1 --org orgmain --server endpoint1 
--configured-gateway-service gw_service_1

This example deletes myextension version 1.0.0 that is in catalog1 of the orgmain organization, and is paired with endpoint1.

extensions get The extensions:get command retrieves the definition file for a specific version of an extension.

The parameters are as follows:
--scope
Specifies whether you want to clone the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
org
Sets the scope to the organization.
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
<extension_name>:<version_number>
Specifies the name and version number of the extension.
Note: extension_name is the extension name, not the file name.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
apic extensions:get --scope catalog|space 
extension_name:version_number 
--catalog | -c catalog_name 
--org | -o org_name 
[--space space] 
--server | -s mgt_server_endpoint 
--configured-gateway-service gw_service_name
Example:
apic extensions:get --scope catalog myextension:1.0.0 
--catalog catalog1 --org orgmain --server endpoint1 
--configured-gateway-service gw_service_1

This example gets myextension version 1.0.0 that is in catalog1 of the orgmain organization, and is paired with endpoint1.

extensions list The extensions:list command lists all versions of an extension given the extension name.

The parameters are as follows:
--scope
Specifies whether you want to clone the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
org
Sets the scope to the organization.
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
<extension_name>
Specifies the name of the existing extension.
Note: This is the extension name, not the file name.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
apic extensions:list --scope catalog|space 
extension_name
--catalog | -c catalog_name 
--org | -o org_name 
[--space space]
--server | -s mgt_server_endpoint 
--configured-gateway-service gw_service_name
Example:
apic extensions:list --scope catalog my_extension 
--catalog catalog1 --org my_org --server endpoint1 
--configured-gateway-service gw_service_1

This example lists all versions of the extension my_extension that are paired with endpoint1, are in catalog1, and in the my_org organization.

extensions list-all The extensions:list-all command lists all of the extensions that are available in a Catalog or Space. This is the default command if you enter only apic extensions.

The parameters are as follows:
--scope
Specifies whether you want to clone the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
org
Sets the scope to the organization.
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
apic extensions:list-all --scope catalog|space 
--catalog | -c catalog_name 
--org | -o org_name 
[--space space]
--server | -s mgt_server_endpoint 
--configured-gateway-service gw_service_name
Example:
apic extensions:list-all --scope catalog 
--catalog catalog1 --org my_org  --server endpoint1 
--configured-gateway-service gw_service1

This example lists the extensions that are paired with endpoint1, are in catalog1, and in the my_org organization.

extensions update The extensions:update command replaces the information of an existing version of an extension with the information in an external file.

The parameters are as follows:
--scope
Specifies whether you want to clear the extensions in a Catalog or Space. The following options are available:
catalog
The command is to be applied to Catalog
space
The command is to be applied to a Space in a Catalog. When Spaces are enabled in a Catalog, you must set the scope to space and supply the --space parameter.
--server or -s <management_server_endpoint>
Specifies the server endpoint.
--catalog or -c <catalog_name>
Specifies a single Catalog with the Catalog name.
--space
Specifies the name of a Space in a Catalog. The --space parameter is required if the Catalog has Spaces enabled, in which case you must also include --scope space in the command.
--org or -o <organization_name>
Specifies a single organization with the organization name.
--configured-gateway-service <service_name>
Specifies the name of the gateway service.
<extension_name>:<version_number>
Specifies the name and version number of the extension.
Note: extension_name is the extension name, not the file name.
<extension_file>
Specifies the name of the extension file that contains the new information for your extension.
Note: This is the OpenAPI file name, not the name of the extension.
apic extensions:update --scope catalog|space 
extension_name:version_number 
extension_file 
--catalog | -c catalog_name 
--org | -o org_name 
[--space space]
--server | -s mgt_server_endpoint 
--configured-gateway-service gw_service_name
Example:
apic extensions:update 
--scope catalog extension1:1.0.0 extension2.yaml 
--catalog catalog1 --org my_org --server endpoint1 
--configured-gateway-service gw_service1

This example updates extension1 version 1.0.0 that is paired with endpoint1, in catalog1, and in the my_org organization, from the file extension2.yaml.