Running APIs locally

The developer toolkit includes a Micro Gateway and a Node.js process manager that you use to test APIs and applications. You can optionally set a IBM® DataPower® Gateway Docker container to test more complex features.

Important: From IBM API Connect Version 5.0.8.7, some commands are no longer supported by the API Connect toolkit. Such commands are indicated on this page by the V5.0.7 and earlier icon.
Important: IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.
[V5.0.7 and earlier]

Creating and running a service

Use the services command to manage running processes for testing APIs and applications. By default, the actions for the services command work on the project or directory where you executed the command, enabling you to manage services for multiple projects concurrently and independently.

Some of the most common actions with the services command are:

  • apic services - List the local running services (alias for services:list).
  • apic start - Start the local services (alias for services:start).
  • apic stop - Stop the local services (alias for services:stop).
  • apic stop --all - Stop all services across all projects.
Note: When you run a project locally, it is also known as a "service."

[V5.0.7 or later]If you want to use the IBM DataPower Gateway Docker image for testing your API locally, see Testing APIs with the IBM DataPower Gateway for details.

The following procedure is a typical workflow to create a LoopBack® project, start the Micro Gateway and the Node.js server running the LoopBack application, and test the API using the endpoint exposed by the Micro Gateway.

  1. Create a LoopBack application project called climbon in a climbon directory:
    apic loopback --name climbon
  2. Update the API and application development artifacts.
  3. Test the project (service) locally.[V5.0.7 and earlier]
    apic start
    [V5.0.7 or later]Note: If the security policy provider is set to DataPower Gateway, this command will attempt to download a Docker container. For more details, see Testing APIs with the IBM DataPower Gateway.
  4. Update the API and application development artifacts as required.
  5. Restart the services so they run with the latest artifact definitions, and re-test.[V5.0.7 and earlier]
    apic stop
apic start
[V5.0.6 or later]Note: You can also use the API Explore tool to test and explore your APIs. Ensure that your local test servers are running, then run the command apic explore. The API Explore tool opens, and shows the operations, definitions, and documentation for all of the APIs that are contained in your project directory. You can specify a single API to explore by specifying the name of the API in the command. The left pane of the Explore window can be used to select an operation to test. The center pane displays summary information about the endpoint, including its parameters, model instance data, and response codes, and the right pane provides template code to call the endpoint. Including the option -e or --external in the command, opens the Explore tool on 0.0.0.0 instead of the default 127.0.0.1. This option binds the server to all IP addresses on the machine, and makes the tool accessible on the wider network.

Viewing logs

When running services and testing APIs and applications, it's often useful to view the Micro Gateway and Node.js LoopBack logs by using the apic logs command. For example:

Command Description
apic logs View the logs for the default service (alias for services:logs)
apic logs --service service_name Use apic services to list the service names.
Set the log-level service property to determine the level of logging detail for the local application and Micro Gateway. The value must be one of:
  • debug - Include all messages in the log. This is the most verbose log level, and is useful for debugging.
  • info - Include messages of "info" level and more severe in the log.
  • warning - Include only messages of "warning" level or more severe in the log.
  • error - Include only messages of "error" level and more severe in the log.
  • fatal - Include only messages of "fatal" (the most severe) level in the log.