Import and Export APIs

Import and Export APIs
calac41
When you export your API, a backup, or copy of your API is created. A typical use case is the life cycle operation of moving a system from development to production. For example, you can export an API from API Server-1 as a file, export the file into a source control system (SCS), and then import it as an API into API Server-2.
In this article:
3
Export APIs
You export your API as either a JSON or ZIP file. This file contains the metadata–the resources, custom endpoints, functions, rules, data sources, virtual and physical relationships, JavaScript libraries, timers, listeners, connections and roles–for the current API. When you export your API and the API is using the 
built-in authentication
 authentication provider, 
CA Live API Creator
 exports the API users that are defined in API Creator. You can check in the exported file into an SCS, view the file in a text editor, or import the file as another API.
 
Prerequisites:
 
Ensure that you have completed the following prerequisite steps before exporting your API:
  • You have deleted each data source that your API is not using or that your API does not require. For example, you might have test/dev data sources.
    For more information about how to delete a data source, see Database Connectivity.
  • You have cleared the 
    Used
     checkbox for each JavaScript library that your API is not referencing.
    For more information about this checkbox, see Logic Libraries.
You can export APIs using the following methods:
Export Using API Creator
Follow these steps:
  1. From the APIs page, open the API that you want to export.
    The API Properties Details tab appears.
  2. Click 
    Export
    .
  3. Complete the following fields, and then click 
    Export
    :
    Export type
     
    The type of file you want 
    CA Live API Creator
     to use as your exported API.
    Options:
     
      • JSON formatted project:
         You want to export your API in JSON file format.
      • Compressed ZIP file: 
        You want to export your API in ZIP file format, with the API details reflected in a hierarchy of directories and files.
    Password Export
     
    Defines if you want 
    CA Live API Creator
     to include your data source password in the API export file, and if you want it included, in what form you want it included.
     
    Options:
     
      • Do not export data source passwords:
         You do not want to include your data source passwords in the API export file. This option is the most secure.
         
      • Encrypt data source passwords:
         You want to include your data source passwords in the API export file in encrypted form.
      • Export data source password in plaintext:
         You want to include your data source passwords in the API export file in plaintext form. This option is not secure.
        Best Practice: 
        If you are in the early stages of development, we recommend that you export data source passwords in plaintext. You can change your passwords after you import an API or (if you are scripting the import process) while you are scripting the import process.
        For more information about the team development best practices, see Team Development.
Your API is downloaded as a JSON or ZIP file.
Export Using Scripts or API Calls
Scripting is based on the underlying concepts of programmatic API creation. Some examples of scripting the export/import process include automating the life cycle operation of moving an API from development to production or verifying that your API matches your SCS.
You can script the import and export of your API using the following methods:
You can pass in options while scripting the import and export of your API. For more information, see the "Advanced DevOps API Administration" section.
The business to business (B2B) sample illustrates the deployment of a system. For more information, see the Business to Business Example.
Script the Export and Import of your API using cURL Commands 
Your API definitions, including the resources, logic, security, filters, and Data Explorer settings, are stored in the admin database. These settings are the contents of the JSON or ZIP file export. You can access these settings (APIs) by way of the Admin API. Scripting the import and export of APIs using cURL commands uses the @export endpoint within the Admin API.
Export Examples:
 
Export is a GET on the 
@export
 endpoint.
The following code block shows an example of scripting the export of the 
Demo
 API to a JSON file using a cURL command:
curl -H "Authorization:CALiveAPICreator ${apikey}:1"
-X GET "http://localhost:8080/rest/abl/admin/v2/@export?projectId=2000" -o "demo_local.json"
The following code block shows an example of scripting the export of the 
Demo
 API to a JSON file using a cURL command:
curl -H "Authorization:CALiveAPICreator ${apikey}:1"
-X GET "http://localhost:8080/rest/abl/admin/v2/@export?urlfragment=demo" -o "demo_local.json"
Import Examples:
 
Import is a POST on the 
@import
 endpoint.
The following code block shows an example of scripting the import of an API using a cURL command:
-- Import API in JSON format
curl -H "authorization: CALiveAPICreator ${apikey}:1" --output import.log --insecure -v --fail
--form "[email protected];type=application/json"
"$http://localhost:8080/rest/abl/admin/v2/@import?namecollision=rename_new&errorhandling=standard"
-- Import API in ZIP format
curl -H "authorization: CALiveAPICreator ${apikey}:1" --output import.log --insecure -v --fail
--form "[email protected];type=application/zip"
"$http://localhost:8080/rest/abl/admin/v2/@import?namecollision=rename_new&errorhandling=standard"
For more information about the endpoints and attributes that the Admin API provides to create APIs, see API Creation By REST.
Script the Export and Import of your API using the Admin CLI
You can manage the import and export of your API using the Admin CLI, 
lacadmin
 (or the alias 
liveapicreatoradmin
).
Export Examples:
 
You can script the export of your API in ZIP or JSON format using the 
export
 command.
For more information about the syntax for this command, see Admin CLI documentation.
The following code block shows an example specifying the API that you want future calls to use, and then scripting the export of the 
Demo
 API in ZIP format using the Admin CLI:
$lacadmin api use --url_name demo $lacadmin api export --file project_demo.zip --format zip
The following code block shows an example of scripting the export of an API in JSON format that includes your data source passwords in the API export file in plaintext form using the Admin CLI:
$lacadmin api export --file project_demo.json --format json --passwordstyle plaintext
Import Examples:
 
You can script the import of your API in ZIP or JSON format using the 
import
 command.
For more information about the syntax for this command, see Admin CLI documentation.
The following code block shows an example of importing the 
project_demo.json
 file, replacing the existing file with the exported file, and reporting errors at the standard level:
$lacadmin api import --file /users/jdoe/project_demo.json --namecollision replace_existing --errorhandling standard
The following code block shows an example of importing the 
project_demo.zip
 file, disabling and renaming the existing file, and reporting errors at the best efforts level:
$lacadmin api import --file project_demo.zip --namecollision disable_and_rename_existing --errorhandling best_efforts
Script the Export and Import of your API using Node SDK
The 
APICreatorSDK
 Node SDK npm package simplifies API access for Node.js applications. 
APICreatorSDK
 includes services that, for example, make auth IDs transparent. You can manage your APIs using 
APICreatorSDK
 by writing Node applications and by employing them in DevOps scripts.
For more information about how to create your API using 
APICreatorSDK
, see API Creation by NodeJS.
Perform Code Review Activities
As an API developer that is part of a team, you can perform code review activities, such as code diffs and merges, offline using the JSON file or ZIP file extract. You can change the contents as part of code review, and then check in your final code to an SCS.
Do not change the structure of your JSON or ZIP file.
For more information about team development, see Team Development.
The JSON File Extract
The JSON file extract represents the entire content of the selected API, including all JavaScript libraries used in the API. Most of your API definitions are contained in the JSON API export file, including the code, such as JavaScript event handlers. The JSON content is organized to reflect similar operations that are seen in 
CA Live API Creator
. The entries in the JSON file extract are prefixed with a notation to indicate a file or directory entry.
The following code snippet shows how 
CA Live API Creator
 simplifies code comparison and code merges that come from multiple API developers by breaking down the JSON content into segments:
{d} - Directory
{f} - File
File Extensions:
.json JSON object definition files
.js JavaScript for a specific object (zero byte files are placeholders)
.sql SQL definitions used by FreeSQL and Rule qualifications
.html HTML formatted files used in topics
.md Markdown format for Readme files (placeholder for empty directories)
The following code block shows an example of a JSON file:
"{f}api.json": {
"name": "demo_new",
"urlFragment": "test",
"comments": null,
"isEnabled": true,
"authProviderName": "Built-in authentication"
},
"{f}exportoptions.json": {
"passwordStyle": "ENCRYPTED"
}
The following diagram shows an example of the JSON format that 
CA Live API Creator
 creates when you export your API in JSON file format:
demo_json.png
The ZIP File Extract
The ZIP file extract is in the correct hierarchy of directories and files. The following image shows an example of the directory structure of exported APIs in ZIP format:
demo_zip.png
Add the Custom Authentication Provider to the TeamSpace
If your API uses a custom JavaScript authentication provider and you are moving your API from one TeamSpace to another, add the authentication provider to the TeamSpace to which you are importing your API. API Server preserves the authentication provider during API import if it can identify the authentication provider by its name. If API Server cannot preserve the authentication provider, it defaults the authentication provider for the API to the 
built-in authentication
authentication provider.
For more information about this step in the team development process, see Team Development.
Import APIs
You can import the exported JSON or ZIP file into your API using the following methods:
 
Prerequisite:
 
If the exported API (the JSON file) that you want to import references libraries and it requires access to JavaScript libraries and the exported API is from a 
CA Live API Creator
 version before 4.1, you have added those libraries to the API.
For more information about how to load logic libraries, see Logic Libraries.
Import Using API Creator
Follow these steps:
 
  1. In API Creator, from the APIs page, click 
    Import
    .
    The Import API window opens.
  2. Complete the following steps:
    1. Click 
      Select file to upload
      , select the exported JSON or ZIP file that you want to import, and then click 
      Open
      .
    2. Select one of the following options from the 
      Import Options
       drop-down, and then click 
      Import
      :
      • Rename API if API name or URL fragment exist
      • Disable and rename existing API if API name or URL fragment match
      • Do not import if API name or URL fragment conflict
         
      • Replace existing API if API name or URL fragment match
      Default:
       Rename API if API name or URL fragment exist
    The JSON or ZIP file is imported into API Server as a new API.
  3. If you imported the API from an exported JSON file that includes active connections and listeners, enable your API.
    CA Live API Creator
     marks the connections as active and restarts the listeners.
    For more information about connections and listeners, see Creating Listeners.
Your API is imported.
Import Using Scripts or API Calls
 If you are scripting the import process and the exported JSON or ZIP API export file that you are importing into your API does not include the data source passwords and other security information, you can change your data source passwords while you are scripting the import process.
Import APIs While Running in a Cluster
Use the following process:
 
  1. Stop all nodes in the cluster.
  2. Import your API.
  3. Restart the nodes.
Fix the Imported API
If the exported JSON or ZIP API export file that you imported into your API 
does not include
 data source passwords and other security information (you exported your API and selected the 
Do not export data source passwords
 option), you must resupply this information. The following procedure defines how to resupply this information in your API using API Creator.
If the exported JSON or ZIP API export file that you imported into your API 
includes
 encrypted data source passwords (you exported your API and selected the 
Encrypt data source passwords
 option), by default, 
CA Live API Creator
 encrypts the security information, including the data source passwords, using the encryption key that 
CA Live API Creator
 includes. You can define the encryption key that you want 
CA Live API Creator
 to use to encrypt the security information by defining your own encryption key for your data source passwords.
For more information about how to define your own encryption keys for your data source passwords, see Manage Encryption Keys.
Follow these steps:
 
  1. Respecify the data source password by completing the following steps:
    1. With your API open, in the Create section, click 
      Data Sources
      .
    2. Respecify the data source password in the 
      Password
       field, and then save your changes.
  2. If you imported the API from an exported JSON file that includes active listeners and connections, respecify the passwords for each connection by completing the following steps:
    1. In the Manage section, click 
      Listeners
      .
    2. Click the 
      Connections
       tab.
    3. Click the 
      Parameters
       tab.
    4. Respecify the 
      password
       parameter value, and then save your changes.
  3. Verify the authentication provider and the URL name for your API by completing the following steps:
    1. In the Create section, click 
      API Properties
      .
      The Details page appears by default.
    2. Verify the authentication provider in the 
      Authentication provider
       field.
    3. (Optional) Respecify the URL name for your API in the 
      URL fragment
       field, which includes the timestamp of the import, and then save your changes.
  4. If you are using the 
    built-in authentication
     authentication provider, specify the passwords for the API users by completing the following steps:
    1. In the Manage section, click 
      Users
      .
      The API Users page appears. 
    2. Specify the password for the API user in the 
      Password
       field, and then save your changes.
      For more information about how to manage API users, see Manage API Users using the Built-in Authentication Provider.
The imported API is fixed.
Advanced DevOps API Administration
You can script your DevOps processes using the following advanced Admin CLI commands. 
The Extract and Synchronize Export API Options
You can export your API as a ZIP file and extract the file to a directory using the 
api
 command with the 
extract
 option. You can specify whether to synchronize your API export file with the files that are located in the directory that you specify by using the 
synchronize
 option and setting it to 
replace
. The default value for the 
synchronize
 option is 
merge
. When it is set to merge, your exported API overwrites the existing files in the directory.
The following code block shows an example of scripting the export, extraction, and synchronization of the 
project_demo.zip
 file to the 
demo
 directory using the Admin CLI:
$lacadmin api use --url_name demo
$lacadmin api extract --file project_demo.zip --directory /Users/johndoe/temp/demo --synchronize replace
Export the APIs that are Contained Within a TeamSpace
You can export the APIs that are contained within a TeamSpace using the 
teamspace
 command with the 
exportRepos
 option.
The following code block shows an example of scripting the export of the APIs that are contained within a TeamSpace to the 
allmyapis.zip
 file using the Admin CLI:
$lacadmin teamspace exportRepos --file allmyapis.zip --format zip --passwordstyle encrypted
For more information about how to export the APIs that contained within a TeamSpace, see GitHub.
Export Sections of your API
You can export a specific section of an API using the 
api
 command with the 
export
 option. For example, you can export rules, resources, functions, custom endpoints, or listeners. Export sections of your API if, for example, you want to merge the exported section offline into your the JSON or ZIP file and check it into your SCS.
The following code block shows an example of scripting the export of the 
xyz
 listener from the 
listener
 section of the specified API to the 
listeners.zip
 file using the Admin CLI:
If you want to use the 
section_filter
 option, you can get the section name for this option from the JSON file. Within the JSON file, the section names are identified in the 
{d}
 section. This section defines the reserved keywords for the section names.
lacadmin api export --section listeners --section_filter “name=xyz” --file listeners.zip --format zip
For more information about how to export sections of your API, see GitHub.
Other Export API Options
The following table lists the options that are available when you use the 
export
 action or the 
@export
 endpoint that the Admin API provides and the equivalent options in API Creator:
Option
Export API Option Name
Admin CLI or @export
API Creator Export Option
Include your data source passwords in the API export file. This option is the most secure.
passwordstyle
skip
Do not export data source passwords
Include your data source passwords in the API export file in encrypted form.
encrypted
Encrypt data source passwords
Include your data source passwords in the API export file in plaintext form.
This option is not secure.
plaintext
Export data source password in plaintext
Export all JavaScript libraries with the API.
librarystyle
emit_all
N/A
Export only the JavaScript libraries that are marked as used.
in_use_only
N/A
Other Import API Options
The following table lists the available options when you use the 
import
 action or the 
@import
 endpoint that the Admin API provides and the equivalent options in API Creator:
Import API Option Name
Admin CLI or @import
API Creator Import Option
namecollision
fail
Do not import if API name or URL fragment conflict.
rename_new
Rename API if API name or URL fragment exist.
replace_existing
Disable and rename existing API if API name or URL fragment match.
disable_and_rename_existing
Replace existing API if API name or URL fragment match.
Limitation with Import in IBM WebSphere
If you are running 
CA Live API Creator
 on an IBM WebSphere Java container, you cannot import APIs in ZIP format. The workaround is to export and import your API in JSON format.