Docs‎ > ‎API Creator‎ > ‎Create your API Project‎ > ‎API Properties‎ > ‎

Import and Export API Definitions

API projects are the definitions you create for your data sources. You can import/export API definitions for your API Server. At its most basic, you can export an API definition from API Server-1 into a file, save it in a source control system, and import it on API Server-2. This is effectively a copy of your API. A typical use is the "life cycle" operation to move a system from dev to production.

You can import API definitions in the following ways:
  • Interactively, using Live API Creator.
  • Using scripts or API calls, to make such operations repeatable.
Scripting requires more background. The following examples illustrate with a cURL and NodeJS scripting.

Import and Export Using Live API Creator

You can interactively export an API definition, import the API definition, and define the export file format.

Export an API Project as a JSON File

You can export your API project as a .JSON file download. The export contains all the meta data for the current API project including database schema, business rules, resource endpoints, security definitions for users, and roles. You can save exported .JSON file into a source control system or import it into another account.

With your API project open, click API Properties, Details, Export.

The following image shows the organization of the JSON file. This file is an ordinary text file and can be large. You can view it in a text editor and check it into a source control system.

Important! Do not make changes to the contents of the file.

Import a Previously Exported JSON API Project File

You import your API definition within your open API project or from the Home page. The following procedure explains how to import the file from within your open API project.
  1. With your API project open, click API Properties, Details, Import.
  2. The Import window opens.
  3. Select the exported JSON file you want to import and click OK.
    The file is imported into the API Server.

Fix the Imported Project

The .JSON export file does not include passwords and other key security information. You must re-supply this information.
  1. With your API project open, clear the Short Menu checkbox.
  2. Respecify you database password and save your changes. For more information about database passwords, see Data Sources.
  3. The authentication provider is preserved if possible or defaulted if not. In some case, respecify your authentication provider on the API Properties page.
  4. (If you are using the default authentication provider) Specify the user passwordsFor the sample databases, we recommend that you use Password1. For more information about using the default authentication provider, see Authentication.
  5. (Optional) Respecify the URL name for your API project, which includes the timestamp of the import.
For an example of importing an API project, see the Logic Sample Project.

Import API Definitions using Scripts or API Calls

You can script the export/import procedures. For example, you might want to automate the "life cycle" process of moving an API from development to production. Scripting is based on several underlying concepts, described below.

Live API Creator APIs consist of settings in the Admin Data, not code. You can access these settings (API definitions) through the Admin API. These settings are the contents of the JSON export, shown above.

Access Admin Data using the Admin API

You can use the Admin API to, for example, create an APIFor more information about this API, see Admin API Reference.

Admin APIs use a characteristic URI, for example:
http://localhost:8080/rest/abl/admin/v2/...

The Admin API is distinct from normal APIs, for example:
http://localhost:8080/rest/default/demo/v1/...

Access Admin Data using the ProjectExport Resource

You can access admin data using the ProjectExport resource within the Admin API. Its response data is shown in the "Sample JSON Layout". Export is a GET and import is a POST on ProjectExport using this API.

Manage your API Definitions using the Admin CLI

You can manage your API definitions using the Admin CLI, liveapicreator-admin-cli, which accesses the Admin API. The Admin CLI is a NodeJS application packaged so it operates from the command line.

For more information about the Admin CLI, see 
Admin CLI.

Access the Admin API using Node SDK

The Node SDK simplifies API Access for NodeJS apps, with services to make Auth IDs transparent, etc. You can write Node apps that can be employed in DevOp scripts to manage your API definitions using the Node SDK.

Script the Import Process using cURL

You can script the import process using cURL. You can extend the following example to automate the setting of the database properties and and the authentication provider after import. You can also export the project from the command line using a GET with a filter.

Get an Auth Token

The admin project requires an auth token (apikey). Use the same username and password that you use to log in to the API Creator. The URL will depend on your setup. In this example, we use the Jetty eval server. Change that if you use your own server (e.g., the URI might be https. You can find these using the Rest Lab):

curl -H "Content-Type: application/json" -d '{"username": "admin", "password": "Password1"}' -X POST http://localhost:8080/rest/abl/admin/v2/@authentication

The response includes the auth token (in bold):
{
  "apikey": "e315ecb50cae07c799cfdc7a2567db4e",
  "expiration": "2016-01-05",
  "lastLoginTs": "2016-01-06",
  "lastLoginIP": "123.321.12.21"
}

Import the Project

Given a JSON file myExport.json exported at a prior time, you can import it as a new project using the following command with the Auth token:
curl -H "Authorization: CALiveAPICreator e315ecb50cae07c799cfdc7a2567db4e:1" -H "Content-type: application/json" --data-binary @myExport.json -X POST http://localhost:8080/rest/abl/admin/v2/ProjectExport

This code POSTs to the  ProjectExport resource.

Script the Import Process with the Admin CLI

The following script creates the Business to Business Example. This is an approach to deploying a system from source control artifacts:
(Windows version):
REM  import Script for Northwind-B2B Jetty
echo on
REM  Logon to local  Jetty server (if using a WAR file use http://localhost:8080/APIServer) 
call liveapicreatoradmin logout -a local
call liveapicreatoradmin login -u admin -p Password1 http://localhost:8080/ -a local
call liveapicreatoradmin use local
call liveapicreatoradmin status

REM  Import the Northwind B2B Project, and 'use' it in subsequent commands 
call liveapicreatoradmin project import --file Northwind-B2B.json
call liveapicreatoradmin project use --url_name nwindb2b
call iveapicreatoradmin project update --authprovider 1000

REM  Create the AuthProvider library. 
call liveapicreatoradmin libraries create --name RESTAuthSecurityProviderCreate project --short_name restauth --libtype javascript --ver 1.0 --linkProject  --file RESTAuthSecurityProvider.js  --comments RESTAuthProvider js Demo 

REM  Create a new library (postResourceTo.js), and link it to the current project 
call liveapicreatoradmin libraries create --name postResourceToJS --short_name postjs --linkProject --libtype javascript --ver 1.0 --file postResourceTo.js  --comments postResourceTo 
call liveapicreatoradmin libraries list

REM  Data Sources [optional] for other databases - set the password
call liveapicreatoradmin datasource list
REM call liveapicreatoradmin datasource update --prefix nw --password password1 -- Jetty does not use pw

REM  Auth Providers - link Auth Provider to the current project, using the library loaded above
call liveapicreatoradmin authprovider list
call liveapicreatoradmin authprovider create --name RESTAuthSecurityProviderCreateJS --createFunction RESTAuthSecurityProviderCreate --paramMap logonApiKey=Bzn8jVyfOTiIpW6UQCgy,loginBaseURL=http://localhost:8080/rest/default/nwindb2b/v1/nw%3AEmployees,loginGroupURL=http://localhost:8080/rest/default/nwindb2b/v1/nw%3ARegion --comments 'Uses NW Employees for REST Validation'
call liveapicreatoradmin authprovider linkProject --name RESTAuthSecurityProviderCreateJS

REM  Import the Pavlov API project
call liveapicreatoradmin project import --file PavlovAPI.json
call liveapicreatoradmin project list
call liveapicreatoradmin project update -authprovider 1000

REM  close connections
call liveapicreatoradmin logout -a local
(Mac version):
#! /bin/bash
# import Script for Northwind-B2B Jetty

## Logon to local  Jetty server (if using a WAR file use http://localhost:8080/APIServer) 
liveapicreatoradmin logout -a local
liveapicreatoradmin login -u admin -p Password1 http://localhost:8080/ -a local
liveapicreatoradmin use local
liveapicreatoradmin status

# Import the Northwind B2B Project, and 'use' it in subsequent commands 
liveapicreatoradmin project import --file Northwind-B2B.json
liveapicreatoradmin project use --url_name nwindb2b

# Create the AuthProvider library. 
liveapicreatoradmin libraries create --name RESTAuthSecurityProviderCreate project --short_name restauth --libtype javascript --ver 1.0 --linkProject  --file RESTAuthSecurityProvider.js  --comments RESTAuthProvider js Demo 

# Create a new library (postResourceTo.js), and link it to the current project 
liveapicreatoradmin libraries create --name postResourceToJS --short_name postjs --linkProject --libtype javascript --ver 1.0 --file postResourceTo.js  --comments postResourceTo 
liveapicreatoradmin libraries list

# Data Sources [optional] for other databases - set the password
liveapicreatoradmin datasource list
#liveapicreatoradmin datasource update --prefix nw --password password1 -- Jetty does not use pw

# Auth Providers - link Auth Provider to the current project, using the library loaded above
liveapicreatoradmin authprovider list
liveapicreatoradmin authprovider create --name RESTAuthSecurityProviderCreateJS --createFunction RESTAuthSecurityProviderCreate --paramMap logonApiKey=Bzn8jVyfOTiIpW6UQCgy,loginBaseURL=http://localhost:8080/rest/default/nwindb2b/v1/nw%3AEmployees,loginGroupURL=http://localhost:8080/rest/default/nwindb2b/v1/nw%3ARegion --comments 'Uses NW Employees for REST Validation'
liveapicreatoradmin authprovider linkProject --name RESTAuthSecurityProviderCreateJS

# Import the Pavlov API project
liveapicreatoradmin project import --file PavlovAPI.json
liveapicreatoradmin project list

# close connections
liveapicreatoradmin logout -a local 

Script with Node

You can configure node applications to integrate into command lines, so building node apps can be useful for scripting operations. For example, a common operation is to move a system from development to production. The following information shows how to build a node app you can invoke from the command line.

Overview

The Admin API includes a Resource called ProjectExport, which returns the JSON representation of an entire API. So, we can GET it from one API Server, and POST it to another, with a node app that:
  1. Calls getApiExport to obtain the export JSON from the Dev API Server
  2. Calls postApiImport, ...
  3. Which posts this JSON to the Production API Server.

The Admin API runs with the Jetty install of the B2B Example.

Notes:
  • apiDev and apiProduction have the same value - not normally the case.
  • The url contains abl/admin/v2 - this designates that the API is using the Admin data.
  • id fixup (see code comments) ensures that internal admin IDs do not conflict with existing Admin data during import.
  • This is a basic illustration; for real use, consider extending it to
    • provide argument input for Dev / Production servers
    • provide for fixup of passwords
  • The code emits the log shown below. Observe the Execution Complete message occurs early, reflecting the common aync execution model of JavaScript.  JavaScript for logic running in the API Server operates synchronously, providing a much simpler programming model.

..getApiExport reading resource ProjectExport, with filter: equal(name:'Northwind-B2B' )
Execution Complete
..getApiExport finds export: Northwind-B2B
....postApiImport - Posting anApiExport into ProjectExport
....postApiImport - SUCCESS


Code

exportImport

To run this example:
  1. Install the Node SDK
  2. Create the B2B example in the jetty install
  3. Create a new folder, and a file in it called exportImport.js with the code above
  4. On your command line: npm install underscore
  5. Run it with (a number of npm install steps might be required)
node exportImport.js

Scripting Best Practices

Before you export a project to create a production server, we recommend:
  1. Remove unused Data Sources (e.g., you might have test/dev Data Source - remove what is not required).
  2. Uncheck unused Libraries.
Logic_Libraries  are not exported. Development teams should maintain such libraries so they can be reloaded onto the production target.  Your import scripts can reload these libraries using the Admin API.

Finally, you may be deploying to a cluster.  Live API Creator is accessed via normal HTTP(s), so use your normal load balancing approach.  Each of the nodes in the cluster should use the same Admin DB (see this discussion).