Tutorial: Creating and publishing an API definition from the command line

This tutorial shows you how to use the developer toolkit to create an API definition, include it in a Product, and publish the Product to a Catalog in API Manager by using IBM® API Connect Version 5.0.7 and later.

Before you begin

Note: For tutorials about working with the developer toolkit in IBM API Connect Version 5.0.6 and earlier, see Developer toolkit tutorials for V5.0.6 and earlier.

The following diagram shows the sequential flow through the IBM API Connect Developer toolkit tutorials for working with API definitions that call an existing endpoint. Before beginning a tutorial, ensure that you have completed the previous tutorials in the sequence. You can click a tutorial in the diagram to open the instructions for that tutorial.

Tutorial flow diagram for API definitions that call an existing endpoint

About this tutorial

With the developer toolkit, you can create API definition files locally and develop them by using your chosen editor. When you are ready to make them available to application developers, you publish them to a Catalog in API Manager, where they can be managed through their lifecycle. In this tutorial, you will create and publish an API.

To make an API available, it must be included in a Plan, and the Plan must be included in a Product; you then stage the Product to API Manager. In this tutorial, you first create an API, then you create a Product that includes the API. A default Plan, that contains the API, is created automatically in the Product.

Instructions are provided to create and publish an API that represents a banking service for obtaining loan quotations; however, if you want to create and publish your own API, you can adapt the instructions accordingly.

In this tutorial, you will complete the following activities:

Create a local API definition YAML file.
Validate the API definition.
Create a local Product definition.
Validate the Product definition.
Log in to API Manager.
Publish the Product to API Manager.

Display general command-line help information by entering the following command: apic --help or apic -h. Display help information for a specific apic command by entering the following command: apic command_name --help or apic command_name -h.

Create a local API definition YAML file

To create a local API definition YAML file, you use the apim create command.

Complete the following steps:

Create a folder to hold your API and Product definitions, and change to that folder in a command window.
Enter the following command:
```
apic create --type api --title Loans
```
This command creates a file called loans.yaml, and assumes the following defaults:

version 1.0.0

basepath /loans

However, you can supply further command options to override these values.
Examine the contents of the loans.yaml file by opening it in your chosen editor.
Although not part of this tutorial, the API can be further developed by modifying the OpenAPI (Swagger 2.0) definition in the YAML file.

Validate the API definition

To validate the syntactical correctness of the API definition YAML file, you use the apim validate command.

Enter the following command:

apic validate loans.yaml

The validation should complete successfully.

Create a local Product definition

To create a local Product definition YAML file, you use the apim create command.

Complete the following steps:

Enter the following command:
```
apic create --type product --title "Banking Services" --apis loans.yaml
```
This command creates a product definition file called banking-services.yaml that includes a reference to the loans.yaml API definition file that you defined previously. The following defaults are assumed:

name banking-services

version 1.0.0

However, you can supply further command options to override these values. The value of the name property determines the file name.
Examine the contents of the banking-services.yaml file by opening it in your chosen editor. Note that a reference to the loans API is included.
Although not part of this tutorial, you can modify the Product definition in the YAML file; for example, you can add further Plans and APIs.

Validate the Product definition

To validate the syntactical correctness of the Product definition YAML file, you use the apim validate command.

Enter the following command:

apic validate banking-services.yaml --product-only

The validation should complete successfully.

By default, the apic validate command validates the Product definition YAML file and all the API definition files that it references. If you supply the --product-only option, only the Product definition is validated.

Log in to API Manager

Complete the following steps:

Enter the following command:
```
apic login
```
At the prompts, enter the following information:
- Server: The virtual host name or virtual IP address of your Management cluster.
- Username: The user name with which you are registered in API Manager.
- Password: Your API Manager password.
Note: You can also supply your credentials as command parameters. However, if you use the command interactively, your password is hidden.

Stage the Product to API Manager

For application developers to be able to use an API, it must be published to a Catalog. A Catalog has an associated Developer Portal and runtime capability. For example, a simple provider organization might consist of a development Catalog and a production Catalog.

Complete the following steps:

To list the Catalogs that are available in API Manager, enter the following command:
```
apic catalogs --all-organizations --server management_cluster_hostname_or_address
```
You should see the identifier for a Catalog called sb, which corresponds to the development Catalog that is created by default when IBM API Connect is installed; the identifier includes the organization that contains it. For example:
```
apic-catalog://myserver.mydomain.com/orgs/myorg/catalogs/sb
```
Publish the Product to the development Catalog by entering the following command (all on one line):
```
apic publish banking-services.yaml --catalog sb --organization URL_path_segment_of_your_provider_organization 
--server management_cluster_hostname_or_address
```
Note: You can choose only to stage the Product, by supplying the --stage option. If a Product is staged, its APIs are not yet available to application developers, and the Product must be subsequently published by using the API Manager user interface. For more information, see Managing your Products.

Confirm that your Product and its referenced APIs have been published to the development Catalog by entering the following commands:

apic products --catalog sb --organization URL_path_segment_of_your_provider_organization --server management_cluster_hostname_or_address
apic apis --catalog sb --organization URL_path_segment_of_your_provider_organization --server management_cluster_hostname_or_address

You should see the banking-services Product and the loans API listed.

Note: You can define default values for your management server, Catalog and provider organization so that you do not have to supply them as command options; enter the following command (all on one line):

apic config:set catalog=apic-catalog://management_cluster_hostname_or_address
/orgs/URL_path_segment_of_your_provider_organization
/catalogs/URL_path_segment_of_your_catalog

For example:

apic config:set catalog=apic-catalog://myhost.com/orgs/myorg/catalogs/sb

You can obtain the required value of the catalog configuration property for a specific Catalog from the API Manager user interface; for more information, see Obtaining the publish target URL for a Catalog.

What you did in this tutorial

In this tutorial, you completed the following activities:

Created a local API definition YAML file.
Validated the API definition.
Created a local Product definition.
Validated the Product definition.
Logged in to API Manager.
Defined your Management cluster and your organization.
Staged the Product to API Manager.