API-related operations

Edit online

You can create, update, validate, publish, download, delete, and secure APIs by using simple prompts. Add client credentials, review security, and control where your APIs are published by using guided, confirmation-based commands.

Create draft APIs or API Connect APIs

The Create draft API prompt creates a draft in the API Connect instance. The create API Connect API prompt displays the draft as a file in response, and no draft is created in the API Connect instance. The API definition can be provided as:
  • A URL that links to a Swagger (OpenAPI 2.0), OpenAPI (3.x), or API Connect document.

  • A file upload that contains the API specification.

Note:
  • The user confirmation is required before execution.
  • Only REST proxy APIs can be created from the existing Swagger, OpenAPI, or API Connect documents.
Note: Before creating a Draft API from a file, ensure that the url value in the file is accurate and points to the server where the application is running. You can also update the url in the draft file before publishing it.
  • For Swagger 2.x files: Verify the host and basePath values.
  • For OpenAPI 3.x files: Verify the value of servers > url.
  • For API Connect documents: In addition to the above, check the target-url value in the x-ibm-configuration section.

Example:

If the API file is generated using the "create openapi spec" and "generate python fastapi server code" prompts:

  • If the generated fastapi server code runs on a machine in your network, the url will point to that machine’s hostname or IP address.

  • If the generated fastapi server code is deployed to IBM Code Engine using the "Deploy the application code" prompt, the url is the application URL value obtained when you run the "give deployment status for the application code" prompt.

Table 1. Parameters
Parameter Type Required Description Valid values Default
url string Optional A URL from which a Swagger (OpenAPI 2.0), OpenAPI (3.x), or API Connect document can be downloaded to create the draft API or API Connect API.
  • If the document is in YAML, explicitly set document_format: yaml.

  • Default format, if unspecified: JSON.

 Valid URL that points to a JSON or YAML document. If both url and input_file are provided, url takes priority. None
input_file file Either url or input_file must be provided. If both url and input_file are provided, url takes priority. A file that contains the API definition in JSON or YAML format.

Supported document types:

  • Swagger (OpenAPI 2.0)

  • OpenAPI (3.x)

  • API Connect

 None
gateway_type String Optional The gateway type for which the API definition is created.
  • "datapower-api-gateway"
  • "apigw"
  • "datapower-gateway"
  • "v5gw"
  • "event-gateway"
 "datapower-api-gateway"
document_format String Optional Specifies the format of the API document when url is used. "json", "yaml" "json"
You can use the following prompts to create draft APIs or API Connect APIs.
Table 2. Create a draft API or API Connect APIs
Action Prompt Command
Create draft API 
create draft api from URL
create draft api from URL and with format yaml
create draft api from URL and with format json and gateway type datapower-api-gateway
import api URL
import api @filename
create draft api using @filename
create draft api using @filename and gateway type datapower-api-gateway
 
/create_draft_api url:URL
/create_draft_api url:URL document_format:yaml
/create_draft_api url:URL document_format:json gateway_type:datapower-api-gateway
/create_draft_api input_file:@filename
/create_draft_api input_file:@filename gateway_type:datapower-api-gateway
Create API Connect API 
create apiconnect api from URL
create apiconnect api from URL and with format yaml
create apiconnect api from URL and with format json and gateway type datapower-api-gateway
create apiconnect api using @filename
create apiconnect api using @filename and gateway type datapower-api-gateway
 
/create_apiconnect_api url:URL
/create_apiconnect_api url:URL document_format:yaml
/create_apiconnect_api url:URL document_format:json gateway_type:datapower-api-gateway
/create_apiconnect_api input_file:@filename
/create_apiconnect_api input_file:@filename gateway_type:datapower-api-gateway

Update draft API

The update draft API prompt updates an existing draft API in the API Connect instance. The operation requires the name and version of the draft API and the updated draft content. User confirmation is required before the update is applied.

Table 3. Parameters
Parameter Type Required Description
api_name string Yes Identifier of the draft API to update. The identifier can be in the form of the API name, api_name:version, or the ID of the draft API.
version string No Version of the draft API.
input_file file Yes The file that contains the updated API definition. This file must be an API Connect-specific OpenAPI document, in either JSON or YAML format. This file is used to overwrite the existing draft API content.
You can use the following prompts to update a draft API.
Table 4. Update a draft API
Action Prompt Command
Update draft API 
update draft api DRAFT_API using content from @file_name

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

update draft api with name APINAME and version VERSION and using content from @file_name
create draft api using @filename and gateway type datapower-api-gateway
 
/update_draft_api api_name:DRAFT_API input_file: @file_name
/update_draft_api api_name:APINAME version:VERSION input_file: @file_name

Download a draft API

The download draft API prompt downloads a draft API from the API Connect instance. This operation requires the draft API name, with or without the version number, or the draft API ID as input.

Table 5. Parameters
Parameter Type Required Description
api_name string Yes Identifier of the draft API that needs to be downloaded. This identifier can be in the form of the API name, api_name:version, or the ID of the draft API.
version string No Version of the draft API.
format JSON/YAML No The format of the output file. The default is JSON.
You can use the following prompts to download draft APIs.
Table 6. Download a draft API
Action Prompt Command
Download draft API 
download draft api DRAFT_API
download draft api with name APINAME and version VERSION
download draft api DRAFT_API in yaml format

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

 
/download_draft_api api_name:DRAFT_API
/download_draft_api api_name:APINAME version:VERSION
/download_draft_api api_name:APINAME version:VERSION format:yaml

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

Validate draft API

The validate draft api prompt validates an API draft either from an existing draft or from a file upload. The operation runs immediately without user confirmation and returns the validation results.
Table 7. Parameters
Parameter Type Required Description
api_name string Either api_name or input_file must be provided. If neither is set, the operation fails. If both are provided, api_name takes precedence. Specifies the name of the draft API to validate. This name can be in the form of the API name, api_name:version, or the ID of the draft API.
version string No Version of the draft API.
input_file String required if api_name is not provided A file that contains the draft API definition. The file can be in JSON or YAML format and must contain a Swagger, OpenAPI, or API Connect definition.
catalog String No Name or ID of the catalog to validate against.
gateway_service_names String No A comma-separated list of gateway service names to use for validation while checking against a catalog or gateway.
You can use the following prompts to validate draft APIs.
Table 8. Validate draft API
Action Prompt Command
Validate draft API 
validate api DRAFT_API
validate api with name APINAME and version VERSION
validate api @file_name
validate api DRAFT_API in catalog CATALOG_NAME
validate api DRAFT_API in catalog CATALOG_NAME and gateway service GATEWAY_SERVICE_NAMES
validate api @file_name in catalog CATALOG_NAME
validate api @file_name in catalog CATALOG_NAME and gateway service GATEWAY_SERVICE_NAMES

Note: The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

 
/validate_api api_name:DRAFT_API
/validate_api api_name:APINAME version:VERSION
/validate_api input_file:@file_name 
/validate_api api_name:DRAFT_API catalog:CATALOG_NAME
/validate_api api_name:DRAFT_API catalog:CATALOG_NAME gateway_service_names:GATEWAY_SERVICE_NAMES
/validate_api input_file:@file_name catalog:CATALOG_NAME
/validate_api input_file:@file_name catalog:catalog_name gateway_service_names:GATEWAY_SERVICE_NAMES

Note: The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

Publish APIs

The publish api prompt publishes an API to the API Connect instance. You can publish the API by either:

  • Providing the name of an existing draft API
  • Uploading an OpenAPI specification file that represents the API
Note: User confirmation is required before execution.
Table 9. Parameters
Parameter Type Required Description
api_name string Required if api_file is not provided. The name of the draft API to publish.
api_file string Optional The path to a file that contains the OpenAPI specification. Required if api_name is not provided. The file must be in JSON or YAML format and conform to Swagger or OpenAPI standards.
product_file string Optional The path to a file that contains the product definition that is associated with the API. If not provided, a wrapper product is autogenerated during publishing.
gateway_names string Optional A comma-separated list of gateway service names to which the API is published. If not specified, the API is published to all relevant gateway services that are configured in the target catalog.
catalog string Optional The name or ID of the catalog where the API is published.

If not specified, "sandbox" is used by default.
You can use the following prompts to publish APIs.
Table 10. Publish API
Action Prompt Command
Publish API
  • Publish an API by name (default catalog: sandbox)
    publish api sample
  • Publish an API by name to a specific catalog, for example, test
    publish api sample to catalog test
  • Publish an API by name to a specific gateway and specific catalog.
    publish api sample using gateway gw-service to catalog test
  • Publish an API from an OpenAPI spec file to a specific catalog
    publish api @sample-api.yaml to catalog test
  • Publish an API from an OpenAPI spec file with a product file to a specific catalog
    publish api @sample-api.yaml with product @product.yaml to catalog test
  • Publish an API by name (default catalog: sandbox)
    /publish_api name:sample
  • Publish an API by name to a specific catalog (for example, test)
    /publish_api name:sample catalog:test
  • Publish an API by name to a specific gateway and specific catalog.
    /publish_api name:sample gateway_names:gw-service catalog:test
  • Publish an API from an OpenAPI spec file to a specific catalog
    /publish_api api_file: @sample-api.yaml catalog:test
  • Publish an API from an OpenAPI spec file with a product file to a specific catalog
    /publish_api api_file: @sample-api.yaml product_file: @product.yaml catalog:test

Delete draft API

The delete draft api prompt deletes a draft API from the API Connect instance. This operation requires the draft API name, with or without the version number, or the draft API ID as an input.

Table 11. Parameters
Parameter Type Required Description
api_name string Yes Identifier of the draft API to delete. This identifier can be in the form of the API name, api_name:version or the ID of the draft API.
version string No Version of the draft API.
You can use the following prompts to delete a draft API.
Table 12. Delete draft API
Action Prompt Command
Delete draft API 
delete draft api DRAFT_API

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

delete draft api with name APINAME and version VERSION
 
/delete_draft_api api_name:DRAFT_API
/delete_draft_api api_name:APINAME version:VERSION

Add security to API

The add security to api prompt adds a security scheme to a draft API. You can run this operation by using either an existing draft API or a file that represents a draft. The specified security scheme is added to the available security definitions and is configured for the API.

Behavior

  • When a client secret security scheme is added, a corresponding client ID security scheme is also automatically added and configured.

  • By default, security schemes are configured as header parameters.

    To configure the security schemes as query parameters instead, set the use_query_params_for_apikey_security property to true when this operation is started.

  • You can configure both header and query parameter styles by running this operation multiple times with the appropriate settings.
Note:
  • User confirmation is required before this operation is executed.
  • Only the apiKey security scheme type is supported in this release.
  • oauth2 and Basic Authentication are not supported.
Table 13. Parameters
Parameter Type Required Description
api_name string Yes Identifier of the draft API to which the security scheme will be added. This identifier can be in the form of the API name, api_name:version, or the ID of the draft API. Either api_name or input_file must be provided. If both are specified, api_name takes precedence.
version string No Version of the draft API.
input_file string Required if api_name is not provided A file that contains the draft API definition. The file can be in JSON or YAML format and must contain a Swagger, OpenAPI, or API Connect definition.
security_type   No The type of security scheme to configure. Only apiKey is supported.
client_id Boolean No Indicates whether to configure a client_id security scheme. Set to true to include it in the configuration.
client_secret Boolean No When set to true, both client_id and client_secret schemes are added automatically.
use_query_params_for_apikey_security Boolean No Determines where the security scheme is applied in the API request.
  • false (default): Security is configured as a header parameter.
  • true: Security is configured as a query parameter.
You can use the following prompts to add security to a draft API.
Table 14. Add security to a draft API
Action Prompt Prompt
Add security to a draft API 
add security to api DRAFT_API
add security to api with name APINAME and version VERSION
add client id security to api DRAFT_API
add client id security to api with name APINAME and version VERSION
add client secret security to api DRAFT_API
add client secret security to api with name APINAME and version VERSION
add client id security as a query parameter to api DRAFT_API
add client secret security as a query parameter to api DRAFT_API
add security to api in file @filename
add client id security to api in file @filename
add client secret security to api in file @filename
add client id security as a query parameter to api in file @filename
add client secret security as a query parameter to api in file @filename

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

 
/add_security_to_api api_name:APINAME version:VERSION
/add_security_to_api api_name:APINAME version:VERSION client_secret:true
/add_security_to_api api_name:APINAME version:VERSION use_query_params_for_apikey_security:true
/add_security_to_api api_name:APINAME version:VERSION client_secret:true use_query_params_for_apikey_security:true
/add_security_to_api input_file: @filename
/add_security_to_api input_file: @filename client_secret:true
/add_security_to_api input_file: @filename client_secret:true use_query_params_for_apikey_security:true

Review security of API

The review security of api prompt reviews the security schemes that are defined and configured in a draft API. You can run this operation by using either an existing draft API or a file that represents a draft. This operation runs automatically and returns output without requiring user confirmation.

Table 15. Parameters
Parameter Type Required Description
api_name string Yes Identifier of the draft API to review. This identifier can be in the form of the API name, api_name:version, or the ID of the draft API. Either api_name or input_file must be provided. If both are specified, api_name takes precedence.
version string No Version of the draft API.
input_file string Required if api_name is not provided A file that contains the draft API definition. The file can be in JSON or YAML format and must contain a Swagger, OpenAPI, or API Connect definition.
You can use the following prompts to review the security of a draft API.
Table 16. Review security of a draft API
Action Prompt Command
Review security of a draft API 
review security of api DRAFT_API

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

review security of api with name APINAME and version VERSION
review security of api in file @filename
 
/review_security_of_api api_name:DRAFT_API

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

/review_security_of_api api_name:APINAME version:VERSION
/review_security_of_api input_file: @file_name

Remove security from a draft API

The remove security scheme from draft api prompt removes one or more security schemes from a draft API. You can do this operation on an existing draft API or by using a file that represents the draft.

The specified security schemes are removed from the following locations, if present:

  • The security definitions of the API
  • The list of configured security schemes at the API level
  • Any path or method-level security configurations
Note: User confirmation is required before execution.
Table 17. Parameters
Parameter Type Required Description
api_name string Either api_name or input_file must be provided. If neither is set, the operation fails. If both are provided, api_name takes precedence. The identifier of the draft API from which the security schemes are removed. This identifier can be in the form of the API name, api_name:version, or the ID of the draft API.
version string No Version of the draft API.
input_file String Required if api_name is not provided A file that contains the draft API definition. The file can be in JSON or YAML format and must contain a Swagger, OpenAPI, or API Connect definition.
security_scheme String No The exact name of the security scheme to remove, which is defined in the draft.
remove_all_security_schemes Boolean No Set to true to remove all defined and configured security schemes from the draft. When this parameter is set to true, the security_scheme parameter is ignored.
The following prompts that you can use to remove the security of a draft API:
Table 18. Remove security of a draft API
Action Prompt Command
Remove security of a draft API 
remove security scheme SECURITY_SCHEME_NAME from api DRAFT_API
remove security scheme SECURITY_SCHEME_NAME from api with name APINAME and version VERSION
remove security scheme SECURITY_SCHEME_NAME from file @filename 
remove all security schemes from api DRAFT_API
remove all security schemes from api with name APINAME and version VERSION
remove all security schemes from file @filename

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.

Note: While removing a security scheme from a draft, the exact scheme name as present in the draft need to be provided in the input.
 
/remove_security_from_api api_name:DRAFT_API security_scheme:SECURITY_SCHEME_NAME
/remove_security_from_api api_name:APINAME version:VERSION security_scheme:SECURITY_SCHEME_NAME
/remove_security_from_api security_scheme:SECURITY_SCHEME_NAME input_file: @filename
/remove_security_from_api api_name:DRAFT_API remove_all_security_schemes: true
/remove_security_from_api api_name:APINAME version:VERSION remove_all_security_schemes: true
/remove_security_from_api remove_all_security_schemes: true input_file: @filename

The value of DRAFT_API can be apiname or apiname:version or the ID of the draft API.