Export and import APIs in Jitterbit API Manager

Introduction

From the APIs page, you can export or import APIs to migrate them into other environments or organizations as needed. You can work with a single custom API, OData API, or proxy API, or with a group of APIs.

When you export custom APIs whose services trigger Studio operations (configured on the Services tab), you can optionally include the Studio projects that contain those operations in the export file. When you import the file, the linked projects are created in the destination environment and each API service is connected to its operation, so you do not need to migrate the projects separately in Studio. To migrate a Studio project on its own, see Project exports and imports or Transfer (migrate) a project.

Export APIs

You can export APIs individually or in groups to migrate them to other environments or organizations.

Export a single API from the actions column

Choose the export method based on your current view:

• List view: Hover over the API's Actions column and click Export.
• Card view: Click the actions menu and select Export.

Selecting Export downloads the API to a file named apis-export.apk. This export does not include the API's linked Studio projects. To include them, use Export API from the page header (see Export one or more APIs).

Export one or more APIs

To export one or more APIs, click Export API in the header of the APIs page to open the configuration screen. The export has two steps: Choose APIs and Export. In step 1, configure the following settings to export a group of APIs:

• Environment: Use the menu to select the environment of the APIs to be exported.

• Include linked Studio projects: Select to include in the export the Studio projects that contain the operations that the selected APIs trigger. This option is disabled when you select only proxy APIs or OData services, which do not have linked Studio projects. The option is enabled when a selected API is a custom API, including a custom API that has no linked projects. When you select a mix of API types, the option applies only to the custom APIs. Selecting this option opens the Components pane, where you choose which project components to export. For more information, see Include linked Studio projects.

• Select APIs to export: After you select an environment, a table lists all APIs within that environment.

  • Select: Select the APIs to export. Use the checkbox in the header column to select all APIs at once.

  • API: Shows the name of the API.

  • API public name: Shows the Service Root of the API service URL.

  • Version: Shows the version of the API, as entered during API configuration.

  • Type: Shows the type of API (custom, OData, or proxy).

  • Linked projects: For custom APIs whose services trigger Studio operations, shows the names of the Studio projects that contain those operations. When an API uses more than one project, the first is shown with a count of the others (for example, +1).

  • Status: Shows whether the API is a draft, published, or published with a draft. For more information, see List view.

  Click the caret to the left of a custom API to expand it. The expanded row shows the following read-only tables:

  • API services: Shows the Service name, Method, Path, and Response type of each API service.

  • Linked project(s) to be exported: Shows the Source project, Operation, Endpoints, and Status of each linked operation. The Status column shows one of the following values:

    • Ready to export: API Manager found the project and operation and can include them.
    • Operation not found: API Manager could not find the operation. The API is exported without its Studio project and operation.
    • No permission: You do not have permission to export the project. The API is exported without its Studio project and operation.

• Export: Click to export the selected APIs and move to step 2, where a summary of the export is displayed (see Export summary).

• Download: Available in step 2 after a successful export. Click to download the selected APIs to an APK file named apis-export.apk.

• Back: Available in step 2. Click to return to step 1.

• Cancel: Click to cancel the export and return to the APIs page.

Include linked Studio projects

When you select Include linked Studio projects, the export file contains the following:

• The selected API definitions.
• The complete Studio project that contains the operation that each API service triggers. The entire owning project is included, not only the linked operation.
• Information that identifies which project and operation each API service uses.

A project used by more than one selected API or API service is included only once.

When you select the option, the Components pane lists what the export contains:

• APIs, API services, and Studio projects: Always included. You cannot clear these.
• Project variable values, Credentials, Email notifications, and Schedules: Selected by default. Clear any that you do not want to include. Each works the same way as the corresponding option in a Studio project export. For more information, see project variables, email notifications, and operation schedules.

Credentials and other protected values are not exposed unless you select Credentials. This component may be unavailable depending on your organization's policies.

When you select the option, API Manager checks that each linked project and operation exists in the environment and that you have permission to export the project. If a project or operation cannot be found, or you do not have permission to export a project, a Some content will be excluded warning appears in the Components pane. The warning names the affected API, project, and operation, and states that the API will be exported without its Studio project and operation. You can still export the API definitions.

To export the API definitions, you need the same API Manager permissions as for any export. To include linked projects, you also need permission to export the projects in the source environment (see role permissions and environment access levels). If you can export an API but not one of its linked projects, the API is exported without that project's content.

Export summary

After a successful export, step 2 displays a message confirming the export and the following tables:

• APIs exported: Shows the API, API public name, Version, Type, and number of Services of each exported API. For custom APIs, Linked projects shows the names of the included projects.

• Projects exported: Shown when you include linked projects. For each project, shows the Project name, the APIs using project, the number of Operations included, and the Status. A status of Ready to export indicates that the project was included in the export. A status of Project not found with 0 operations indicates that the project's content was not included in the export.

• Warning notes: Shown when the export completes with warnings, such as when a linked project or operation could not be found or you do not have permission to export a project. The message states how many APIs were exported and that the Studio projects and operations that were not exported must be provided in the destination environment. When you import a file that does not include a custom API's Studio project and operation, API Manager creates the API as a draft (see Import progress and results).

Click Download to save the export file.

Import APIs

To import APIs, click Import from the APIs page. The import has three steps: Choose APIs, Projects and endpoints, and Deployment. What you configure in steps 2 and 3 depends on the contents of the APK file:

• File with linked Studio projects: Each unique project in the file is created as a new project in the destination environment. API Manager does not reuse, update, overwrite, or merge an existing project. In steps 2 and 3, you configure and deploy the projects.

• File without linked Studio projects: Steps 2 and 3 display a message that there are no linked Studio projects to import.

To import APIs, you need the same API Manager permissions as for any import. To import a file with linked Studio projects, you also need Write access to the destination environment, which is required to create the projects.

Throughout the import, the Importation summary pane on the left shows the Environment menu and the uploaded file. The Environment menu is unavailable after step 1. To change it, return to step 1.

Step 1: Choose APIs

In this step, you choose the destination environment, upload the APK file, and select and configure the APIs to import.

• Environment: Use the menu to select the environment you want to import the APIs into.

• Upload: Click to browse to an APK file that you previously exported from API Manager, or drag and drop the file onto the upload area. After the upload, the file name appears in the upload area. Click next to the name to remove the file.

After you upload a file, the Select API(s) to import table lists the APIs in the file:

• Select: Select the APIs to import. Use the checkbox in the header column to select all APIs at once.

• API: Shows the name of the API. Click the name to edit it.

• Service Root: Shows the Service Root of the API service URL. Click the value to edit it.

• Version: Shows the version of the API. Click the value to edit it.

• Type: Shows the type of API (custom, OData, or proxy).

• Publish API: Use the toggle to publish the API when the import completes. The toggle is on by default. APIs for which the toggle is off are saved as drafts.

Click the caret to the left of an API to view and configure it:

• Configuration:

  • User roles: Use the menu to select one or more user roles for the API. The selected roles appear below the menu.

  • Security profile: Optionally, use the menu to select an existing security profile to restrict access for consumption of the API.

• API services: Shows the Service name, Method, Path, Project, Operation, and Response type of each API service. Click a service name to edit it. Click Reset to restore the original service names.

Click Next to continue.

Step 2: Projects and endpoints

In this step, you configure the projects that API Manager creates in the destination environment.

If the APK file does not include linked Studio projects, the Projects to be imported table displays a message that there are no linked Studio projects to import. Click Next to continue.

If the file includes linked Studio projects, a project used by more than one selected API is listed and imported only once. The Projects to be imported table shows the following:

• Source Project: Shows the name of the project in the source environment.

• Target Project: Shows the name of the project to be created in the destination environment. The default name is the source project name followed by the date and time. Click the name to edit it. The name must be valid and must not match an existing project in the destination environment.

• APIs Using Project: Shows the selected APIs that use the project.

• Total Operations: Shows the operations in the project that the selected APIs use.

• Endpoints: Shows the number of endpoints in the project. A warning icon indicates that one or more endpoints need configuration. A check mark indicates that all endpoints are configured. The column is blank when the project has no endpoints.

Click the caret to the left of a project to expand it. Under Assign user roles, use the User roles menu to select one or more user roles for the project.

When a project has endpoints that need configuration, the expanded project also shows an Endpoints table. A message indicates that endpoints must be configured before operations can be validated for deployment, and Next is disabled until you configure them. For each endpoint, the table shows the following:

• Source endpoint: Shows the name of the endpoint in the source project.

• Connection type: Shows the type of connection, such as FTP.

• Target endpoint: Use the menu to select the endpoint in the destination environment to use for the imported project. The menu lists only endpoints of the same connection type in the destination environment. The default is None. For how Studio handles endpoints when you import a project, see Import a project.

• Status: Shows whether the endpoint is configured. Missing configuration indicates that you have not selected a target endpoint. Configured indicates that you have.

Click Next to continue.

Step 3: Deployment

In this step, you review and choose which operations API Manager deploys in the destination environment. For more information about deployment, see Deploy a project and Deploy and execute an operation.

If the file does not include linked Studio projects, the Projects to be created and deployed table displays a message that there are no linked Studio projects to import. Click Import to start the import.

If the file includes linked Studio projects, the Projects to be created and deployed table shows the Target Project, its Endpoints, and a summary of its Operations. A status of All ready indicates that every operation in the project is ready to deploy.

Click the caret to the left of a project to expand it. The Operations table shows the following:

• Operation: Shows the name of the operation.

• Linked API services: Shows the API services that use the operation.

• Deployment readiness: Shows whether the operation is ready to deploy. Operations must be valid before you can deploy them.

• Deploy: Use the toggle to deploy the operation after the project is created.

Use the Only used in APIs toggle to limit the table to operations that the selected APIs use. Click Reset to return the Deploy toggles to their default settings.

Click Import to start the import.

Import progress and results

When you click Import, a checklist shows the progress. When the import completes, a message indicates whether the APIs and their linked projects were imported successfully or with warnings, and the following tables are displayed:

• APIs imported:

  • API Name, Service Root, Type, and Services: Show the name, service root, type, and number of services of each imported API.

  • Projects: Shows the number of projects that the API uses.

  • Publish API: Shows whether the import published the API. The toggle is off for an API that was created as a draft, even if you turned it on before the import.

  • Status: Shows the status of the imported API: Published or Draft. For more information about API statuses, see List view.

  • Notes: Shows information about the import, such as whether the operations deployed successfully. When an API is created as a draft, this column lists the operations that could not be deployed.

  • Action: Click Go to API to open the API details drawer.

• Projects imported:

  • Project: Shows the name of the project created in the destination environment.

  • APIs Using Project: Shows the number of imported APIs that use the project.

  • Operations: Shows the number of operations in the project.

  • Undeployed Ops: Shows the number of operations that were not deployed.

  • Import Status: Shows whether the project was created in the destination environment (Imported or Not imported).

  • Deployment Status: Shows whether the project was deployed (Deployed or Deployment failed).

  • Action: For an imported project, click Go to Project to open the project in Studio. A project that was not imported has no action, because the project does not exist in the destination environment.

• Used URLs: Shows the number of custom API URLs and proxy API URLs in use, out of the total allowed by the organization's subscription. Only published APIs count toward these totals. For more information, see APIs page header.

• Warnings / Next steps: Shown when an imported API remains a draft because a Studio project that it requires did not deploy successfully. Lists each affected API.

For a file without linked Studio projects, the Projects imported table is empty and the Projects column shows 0 for each API. A custom API cannot be published without a linked operation. Because the file does not include the projects that contain the operations, API Manager creates each custom API as a draft even if Publish API was on. The Notes column lists the operations that could not be deployed, and the Warnings / Next steps message identifies the affected API. To publish the API, edit it, select a project and operation for each service on the Services tab, and then publish it (see Save and publish options).

Consider the following:

• An API is published only when the projects that its services use are deployed. If a required project fails to deploy, the API is created as a draft even when you selected it for publishing. The import results identify the affected API in a warning message and in Warnings / Next steps, and the Notes column lists the operations that could not be deployed. After you resolve the deployment issue, publish the API from API Manager.

• If API Manager cannot find an imported operation that an API service uses, it does not connect that service, and the import is not reported as fully successful.