API development and management commands

A summary of the core commands in the IBM® API Connect developer toolkit.

Authenticating

Use the apic login command to authenticate to an API Manager service, and the apic logout command to remove your local authentication credentials.

Note: When you authenticate successfully, your credentials are stored, in plain text, in the file [Icon indicating that this applies on Linux platforms]

.netrc or

_netrc. Therefore, you should set the file permissions in such a way that your credentials are not accessible by others.

For full details on how to log in to your management server from the CLI, see Logging in to the management server.

Configuring the command-line tool to use TLS certificates

API Manager uses TLS profiles to secure data transmission. For information on how to create a TLS profile in API Manager, see TLS profiles.

To configure the toolkit command-line tool to use certificates to communicate with an API Manager that has TLS profiles that are enabled, follow these steps:

For more information about the NODE_EXTRA_CA_CERTS environment variable, see Node.js documentation.

Creating and managing local files

You create and work with API and Product definition YAML files locally before you stage them to API Manager.

To create a local API definition file, use the apic create:api command. To create a local Product definition file, use the apic create:product command.

Use the apic apis and apic products commands to list API Manager artifacts of the specified type.

To validate the syntactical correctness of a local API or Product definition file, use the apic validate command.

To create a draft API in API Manager from a local API or Product definition file, use the apic draft-apis:create and apic draft-products:create commands, respectively.

Note: If the OpenAPI file that defines your API uses a $ref field to reference a fragment of OpenAPI code that is defined in a separate file, the $ref field is replaced with the contents of the target file before an API is validated, created in draft, staged, or published. For more information, see Using $ref to reuse code fragments in your OpenAPI files.

Working with Catalogs and Spaces

To create a Catalog, use the apic catalog:create command. To view information on a Catalog, use the apic catalog:get command; to list all Catalogs that are contained in organizations that the currently authenticated user is a member of, use the apic catalogs command.

You can use a Space to partition a Catalog so multiple teams can manage Products and APIs independently in a single Catalog. A Space is conceptually like a subcatalog, except that Products and APIs in all Spaces in a given Catalog are published to the same developer portal. For more information about Spaces, see Using syndication in IBM API Connect.

To enable Spaces for a Catalog, use the following command:

apic catalogs:set catalog_name --spaces enabled

Use the toolkit apic spaces commands to create and manage Spaces:

apic spaces - List Spaces contained in a Catalog.
apic:spaces create - Create a Space in a Catalog.
apic:spaces get - Get information on a Space in a Catalog.
apic:spaces set - Set information on a Space in a Catalog.
apic:spaces delete - Delete a Space in a Catalog.

Command summary

The following tables summarize apic commands for API development and management.

Table 1. Summary of general-purpose commands
Command	Description	Subcommands
`apic config`	List and manage configuration variables. For more information, see Using configuration variables. With no subcommand, lists values of defined configuration variables.	`apic config` - Manage configuration variables `apic config:clear` - Delete all configuration variables `apic config:delete` - Delete a configuration variable `apic config:get` - Get a configuration variable `apic config:list` - List the application and global configuration variables `apic config:set` - Set or update configuration variables
`apic create`	Create a draft API or Product definition YAML file.	`create:api` - Create a draft API OpenAPI definition YAML file `create:product` - Create a Product definition YAML file
`apic extensions`	Manage OpenAPI extensions in a Catalog. With no subcommand, lists the extensions in the production Catalog.	`apic extensions` - Extension collection operations. `apic extensions:clear` - Delete all versions of an extension given the name. `apic extensions:clear-all` - Delete all versions of all extensions. `apic extensions:clone` - Download all versions of all extensions to your local drive. `apic extensions:create` - Create an extension. `apic extensions:delete` - Delete an extension by ID, or by name and version. `apic extensions:document` - Get the document for an extension by ID, or by name and version. `apic extensions:get` - Get an extension by ID, or by name and version. `apic extensions:list` - List all versions of an extension given the name. `apic extensions:list-all` - List all versions of all extensions. `apic extensions:update` - Update an extension by ID, or by name and version.
`apic login`	Log in to API Manager.	None. Specify server and credentials with the required flags: `-p, --password` `password` `-r, --realm` `realm`. Determines the identity provider that is used to authenticated the supplied user ID, and the scope of the tasks that can be performed after successful log in. `-s, --server` `mgmt_endpoint_url`. Use the value of the platform API endpoint URL for this entry. `-u, --username` `user_name` For full details on how to log in to your management server from the CLI, see Logging in to the management server.
`apic logout`	Log out from API Manager.	None. Specify server with the required flag: `-s, --server` `mgmt_service`. You can append the port number to the server name if it is not the default value of 443.
`apic validate`	Validate API or Product definition YAML file.	None

Table 2. Summary of commands to manage APIs, Products, and Catalogs
Command	Description	Subcommands
`apic apis`	List and manage APIs that are staged or published to Catalog or Space. Default subcommand is `list-all`.	`apic apis` - API collection operations `apic apis:get` - Get the OpenAPI definition YAML file for an API by name and version, or by ID `apic apis:list` - List an API by name `apic apis:list-all` - List all APIs in a Catalog or Space `apic apis:update` - Update an API by name
`apic apps`	List and manage developer applications that are registered in a consumer organization. Default subcommand is `list`.	`apic apps` - Application collection operations `apic apps:clear` - Clear all applications `apic apps:create` - Create an application `apic apps:delete` - Delete an application by name or ID `apic apps:get` - Get an application object by name `apic apps:list` - List all the applications in a consumer organization `apic apps:update` - Update an application by name or ID
`apic catalogs`	List and manage Catalogs in a provider organization. Default subcommand is `list`.	`apic catalogs:clear` - Clear all Catalogs from provider organization `apic catalogs:create` - Create a Catalog `apic catalogs:delete` - Delete a Catalog by name or ID `apic catalogs:get` - Get a Catalog object by name or ID `apic catalogs:list` - List all the Catalogs in a provider organization `apic catalogs:transfer-owner` - Transfer the ownership of a Catalog to another user `apic catalogs:update` - Update a Catalog by name or ID
`apic catalog-settings`	Manage the configuration settings for a Catalog	`apic catalog-settings:get` - Get the Catalog settings. `apic catalog-settings:update` - Update the Catalog settings.
`apic drafts`	List and manage the draft API and Product definitions in a provider organization. Default subcommand is `list`.	`apic drafts` - Draft collection operations `apic drafts:clear` - Delete all draft APIs and Products in a provider organization `apic drafts:list` - List the draft APIs and Products in a provider organization
`apic draft-apis`	List and manage the draft API definitions in a provider organization. Default subcommand is `list-all`.	`apic draft-apis` - Draft API collection operations `apic draft-apis:clear` - Delete all versions of a draft API by name `apic draft-apis:clear-all` - Delete all draft APIs in a provider organization `apic draft-apis:clone` - Clone all draft APIs in a provider organization `apic draft-apis:create` - Create a draft API `apic draft-apis:delete` - Delete a Draft API by name and version `apic draft-apis:document` - Get the Draft API document by name and version `apic draft-apis:get` - Get the OpenAPI definition YAML file for an API by name and version `apic draft-apis:list` - List all versions of a draft API by name `apic draft-apis:list-all` - List all draft APIs in a provider organization `apic draft-apis:update` - Update a draft API by name and version, supplying the revised OpenAPI definition file `apic draft-apis:update-wsdl` - Update a draft SOAP API by name and version, supplying the revised WSDL definition file in a .wsdl or .zip format Note: There must be a match of the service names in the existing WSDL with the revised WSDL. If a match is found, the WSDL service is converted into a YAML file that is used to update the API. If no match is found, an error message is displayed. `apic draft-apis:validate` - Validates a draft API `apic draft-apis:wsdl` - Get the Draft API WSDL document by name and version
`apic draft-products`	List and manage the draft Product definitions in a provider organization. Default subcommand is `list-all`.	`apic draft-products` - Draft Product collection operations `apic draft-products:clear` - Delete all versions of a draft Product by name `apic draft-products:clear-all` - Delete all draft Products in a provider organization `apic draft-products:create` - Create a draft Product `apic draft-products:delete` - Delete a draft Product by name and version `apic draft-products:get` - Get the Draft Product by name and version `apic draft-products:list` - List the Draft Products `apic draft-products:list-all` - List all draft Products in a provider organization `apic draft-products:publish-all` - Publishes the Draft Product `apic draft-products:update` - Update a draft Product by name and version, supplying the revised definition file `apic draft-products:validate` - Validates a draft Product
`apic members`	List and manage the members of a provider organization, consumer organization, Catalog, or Space. Default subcommand is `list`.	`apic members` - Member operations `apic members:clear` - Delete all members `apic members:create` - Create a member `apic members:delete` - Delete a member by name or ID `apic members:get` - Get a member object by name or ID `apic members:list` - List all members `apic members:update` - Update the member by name or ID
`apic member-invitations`	List and manage member invitations. A member invitation is created when a user is invited to be a member of a provider organization, consumer organization, Catalog, or Space. Default subcommand is `list`.	`apic member-invitations` - Member invitation collection operations. `apic member-invitations:clear` - Delete all member invitations. `apic member-invitations:create` - Create a member invitation. `apic member-invitations:delete` - Delete a member invitation by name or ID. `apic member-invitations:get` - Get a member invitation object by name or ID. `apic member-invitations:list` - List all member invitations. `apic member-invitations:update` - Update a member invitation by name or ID.
`apic orgs`	List and manage provider organizations, and the admin organization. Default subcommand is `list`.	`apic orgs` - Organization collection operations `apic orgs:clear` - Delete all organizations `apic orgs:create` - Create an organization `apic orgs:delete` - Delete an organization by name or ID `apic orgs:get` - Get an organization object by name or ID `apic orgs:list` - List all organizations `apic orgs:transfer-owner` - Transfer ownership of an organization `apic orgs:update` - Update an organization by name or ID
`apic org-settings`	Manage settings for provider organizations, and the admin organization.	`apic org-settings:get` - Get the settings object for an organization `apic org-settings:update` - Update the settings for an organization
`apic policies`	List and manage policies in a Catalog. Default subcommand is `list`.	`apic policies` - Policy collection operations `apic policies:clear` - Clear the Policies `apic policies:clear-all` - Clear all Policies in all collections `apic policies:create` - Create a Policy `apic policies:delete` - Delete a Policy `apic policies:get` - Get the Policy by name and version `apic policies:list` - List the Policies `apic policies:list-all` - List all Policies in all collections `apic policies:update` - Update the Policy by name and version
`apic products`	List and manage Products that are staged or published to Catalog or Space. Default subcommand is `list-all`.	`apic products` - Product collection operations `apic products:clear` - Delete all versions of a Product by name `apic products:clear-all` - Delete all Products `apic products:delete` - Delete a Product by name and version `apic products:execute-migration-target` - Products execute migration target operations `apic products:get` - Get a Product object by name and version `apic products:list` - List all versions of a Product by name `apic products:list-all` - List all Products `apic products:publish` - Publish a Product to a Catalog or Space, supplying the Product definition YAML file `apic products:replace` - Replace a Product with another Product `apic products:set-migration-target` - Set the target Product for migrating subscriptions from a Product `apic products:supersede` - Supersede a Product with another Product `apic products:update` - Update a Product by name and version, supplying the revised Product definition YAML file
`apic identity-providers`	View information about identity providers.	`apic identity-providers` - Identity provider operations `apic identity-providers:list` - List the identity providers.
`apic spaces`	List and manage Spaces contained in a Catalog. Default subcommand is `list`.	`apic spaces` - Space collection operations `apic spaces:clear` - Delete all Spaces from a Catalog `apic spaces:create` - Create a Space in a Catalog `apic spaces:delete` - Delete a Space from a Catalog, by name or ID `apic spaces:get` - Get a Space object by name or ID `apic spaces:list` - List all the Spaces in a Catalog `apic spaces:transfer-owner` - Transfer the ownership of a Space to another user `apic spaces:update` - Update a Space by name or ID
`apic subscriptions`	List and manage subscriptions in a Product or a Catalog. Default subcommand is `list`.	`apic subscriptions` - Subscription collection operations `apic subscriptions:clear` - Clear the Subscriptions `apic subscriptions:create` - Create a Subscription `apic subscriptions:delete` - Delete the Subscription by name or ID `apic subscriptions:get` - Get the Subscription by name or ID `apic subscriptions:list` - List the Subscriptions `apic subscriptions:update` - Update the Subscription by name or ID

Table 3. Summary of other commands for API developers and managers
Command	Description	Subcommands
`apic consumer-orgs`	Manage consumer organizations	`apic consumer-orgs` - Consumer Organization collection operations. `apic consumer-orgs:clear` - Clear the Consumer Organizations. `apic consumer-orgs:create` - Create a Consumer Organization. `apic consumer-orgs:delete` - Delete the Consumer Organization by name or ID. `apic consumer-orgs:get` - Get the Consumer Organization by name or ID. `apic consumer-orgs:list` - List the Consumer Organizations. `apic consumer-orgs:transfer-owner` - Transfer owner to a new member. `apic consumer-orgs:update` - Update the Consumer Organization by name or ID.
`apic consumer-org-settings`	Manage consumer organization settings	`apic consumer-org-settings:delete` - Delete the Consumer Organization Setting. `apic consumer-org-settings:get` - Get the Consumer Organization Setting. `apic consumer-org-settings:update` - Update the Consumer Organization Setting.
`apic groups`	Manage groups	`apic groups` - Group collection operations. `apic groups:clear` - Clear the Groups. `apic groups:create` - Create a Group. `apic groups:delete` - Delete the Group by name or ID. `apic groups:get` - Get the Group by name or ID. `apic groups:list` - List the Groups. `apic groups:update` - Update the Group by name or ID.
`apic invitations`	Manage invitations. An invitation is created when a user is invited to be the owner of a provider organization, consumer organization, Catalog, or Space.	`apic invitations` - Invitation collection operations. `apic invitations:clear` - Delete all invitations. `apic invitations:create` - Create an invitation. `apic invitations:delete` - Delete an invitation by name or ID. `apic invitations:get` - Get the details of an invitation by name or ID. `apic invitations:list` - List all invitations. `apic invitations:update` - Update an invitation by name or ID.
`apic member-invitations`	Manage member invitations. A member invitation is created when a user is invited to be a member of a provider organization, consumer organization, Catalog, or Space.	`apic member-invitations` - Member invitation collection operations. `apic member-invitations:clear` - Delete all member invitations. `apic member-invitations:create` - Create a member invitation. `apic member-invitations:delete` - Delete a member invitation by name or ID. `apic member-invitations:get` - Get the details of a member invitation by name or ID. `apic member-invitations:list` - List all member invitations. `apic member-invitations:update` - Update a member invitation by name or ID.
`apic members`		`apic members` - Member collection operations. `apic members:clear` - Clear the Members. `apic members:create` - Create a Member. `apic members:delete` - Delete the Member by name or ID. `apic members:get` - Get the Member by name or ID. `apic members:list` - List the Members. `apic members:update` - Update the Member by name or ID.
`apic registrations`		`apic registrations` - Registration collection operations. `apic registrations:clear` - Clear the Registrations. `apic registrations:create` - Create a Registration. `apic registrations:delete` - Delete the Registration by name or ID. `apic registrations:get` - Get the Registration by name or ID. `apic registrations:list` - List the Registrations. `apic registrations:update` - Update the Registration by name or ID.
`apic role-defaults`		`apic role-defaults` - Role Default collection operations. `apic role-defaults:clear` - Clear the Role Defaults. `apic role-defaults:create` - Create a Role Default. `apic role-defaults:delete` - Delete the Role Default by name or ID. `apic role-defaults:get` - Get the Role Default by name or ID. `apic role-defaults:list` - List the Role Defaults. `apic role-defaults:list-all` - List all Role Defaults in all collections. `apic role-defaults:update` - Update the Role Default by name or ID.
`apic roles`		`apic roles` - Role collection operations. `apic roles:clear` - Clear the Roles. `apic roles:create` - Create a Role. `apic roles:delete` - Delete the Role by name or ID. `apic roles:get` - Get the Role by name or ID. `apic roles:list` - List the Roles. `apic roles:update` - Update the Role by name or ID.
`apic tasks`		`apic tasks` - Task collection operations. `apic tasks:clear` - Clear the Tasks. `apic tasks:create` - Create a Task. `apic tasks:delete` - Delete the Task by name or ID. `apic tasks:get` - Get the Task by name or ID. `apic tasks:list` - List the Tasks. `apic tasks:update` - Update the Task by name or ID.
`apic user-registries`		`apic user-registries` - User Registry collection operations. `apic user-registries:clear` - Clear the User Registries. `apic user-registries:create` - Create a User Registry. `apic user-registries:delete` - Delete the User Registry by name or ID. `apic user-registries:execute` - Execute a User Registry operation. `apic user-registries:get` - Get the User Registry by name or ID. `apic user-registries:list` - List the User Registries. `apic user-registries:search` - search for users in a user registry. `apic user-registries:test-connection` - Test a User Registry connection. `apic user-registries:update` - Update the User Registry by name or ID.
`apic user-registry-settings`		`apic user-registry-settings:delete` - Delete the User Registry Setting. `apic user-registry-settings:get` - Get the User Registry Setting. `apic user-registry-settings:update` - Update the User Registry Setting.
`apic users`		`apic users` - User collection operations. `apic users:clear` - Clear the Users. `apic users:create` - Create a User. `apic users:delete` - Delete the User by name or ID. `apic users:get` - Get the User by name or ID. `apic users:list` - List the Users. `apic users:request-password-reset` - send a password reset link. `apic users:search-provider` - Search for provider users from an organization. `apic users:update` - Update the User by name or ID.
`apic test`	Test your APIs	`apic test {yaml-files}` - Define the tests. `apic test {yaml-files} --insecureSkipVerify` - Test the APIs with certificate checks disabled. `apic test {yaml-files} --certPath={location of certs folder}` - Specifies the location of the CA certificate if it is not available in the system keystore. `api test {yaml-files} --mTLS --certPath={location of certs folder}` - Test the APIs with `mTLS` enabled. `api test {yaml-files} --config-file={location of config file}` - Define the tests by passing the external configuration.