Working with Drafts

Co-locate your APIs and applications in your local source code control systems to support typical development activities such as commits, branching, merges, continuous integration, and so on. The developer toolkit provides the bridge from the developer's environment to the IBM® API Connect runtime services.

IBM API Connect provides an online development capability called Drafts where you can define API and Product definitions. The apic drafts commands enable synchronization of Product and API artifacts between local source code control systems and drafts.

Similar to the products and apis commands, you can use drafts to push, pull, and clone artifacts. For example:

apic config:set catalog=apic-catalog://mgmnthost.com/orgs/climbon/catalogs/sb    # set the default Catalog
apic login --username some-user --password some-password --server mgmnthost.com  # login into the mgmnthost.com cloud

apic create --type api --title routes --product ClimbOn
apic drafts:push climbon.yaml                             # push climbon:1.0.0 and routes:1.0.0 to drafts
apic drafts                                               # list what is in drafts
apic drafts:get climbon                                   # get climbon:1.0.0
apic drafts:get routes                                    # get routes:1.0.0
apic drafts:pull climbon                                  # pull climbon:1.0.0 and routes:1.0.0 from drafts
apic drafts:clone                                         # pull every Product/api from drafts
apic drafts:clear --confirm drafts                        # clear drafts collection

Note: If the OpenAPI (Swagger 2.0) file that defines your API uses a $ref field to reference a fragment of OpenAPI (Swagger 2.0) code that is defined in a separate file, the $ref field is replaced with the contents of the target file before the draft API is created with the apic drafts:push command. For more information, see Using $ref to reuse code fragments in your OpenAPI (Swagger 2.0) files.

In addition to synchronizing data between local developer source code control systems and drafts, you can publish Products that are in drafts. For example:

apic config:set catalog=apic-catalog://mgmnthost.com/orgs/climbon/catalogs/sb    # set the default Catalog
apic login --username some-user --password some-password --server mgmnthost.com  # login into the mgmnthost.com cloud

apic create --type api --title routes --product ClimbOn
apic drafts:push climbon.yaml                             # push climbon:1.0.0 and routes:1.0.0 to drafts
apic drafts:publish climbon

Although you can develop Products and APIs as drafts on your API Connect Management server by using the API Manager user interface, the preferred practice is to develop them locally. Therefore, if you already have draft Products and APIs in API Manager, either because you were previously a user of IBM API Management Version 4.0 or because you began by creating them there in IBM API Connect Version 5.0, use the apic drafts:clone command to create local versions of them, check them into your local source code control system, and continue developing them there. You can then publish to your Catalogs directly from your source code control system.