Docs‎ > ‎Home‎ > ‎

Import

This page explains how you 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 them in a source control system, and import 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 perform an import in multiple ways:
  • Interactively, using the API Creator, or..

  • Scripts or API calls, to make such operations repeatable
Scripting requires a bit more background, provided below.  We illustrate with a Curl and NodeJS scripting examples.
  

Using API Creator

This section illustrates how to export an API Definition, the export file format, and how to import.

Export

You can export an API Definition using the Export button on the API Properties menu for a selected project (also described here). 


API Exports are JSON files

The export operation creates a JSON file, organized as shown below.  Since it is an ordinary text file (can be large), you can perform typical operations on it: view it in a text editor, check it into a source control system, etc... It is generally not recommended that you make changes to the contents of the file.


Import

The import button will allow API export files to be imported into this API Server:

IMPORTANT : The JSON export does not save certain information - after the API Import is completed: 
    • re-specify you database password(s) (see Data Sources)
    • the Authentication Provider will be preserved if possible, or defaulted if not. In some case, you may have to re-specify your Authentication Provider on the API Properties dialog
    • specify user passwords (if you are using the default Authentication Provider)
    • optionally, you may also want to re-specify the Project URL (which will include the timestamp of the import)

Scripting Concepts

In addition to interactive import as described above, 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.

APIs are Admin Data (not code)

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.

Accessible via the Admin API

Admin data can be access via a special system API called the Admin API.  You can explore the Admin API Reference here.  You can use this, for example, to create an API.

Admin APIs use a characteristic URI:

http://localhost:8080/rest/abl/admin/v2/...

which is distinct from a normal API, whose URL would look something like:

http://localhost:8080/rest/default/demo/v1/...

Project Export Resource

Within the Admin API, we have defined a special Resource called the ProjectExport resource.  Its response data is shown above ("Sample JSON Layout").  So, the basic idea:
  • Export is a Get on ProjectExport using the Admin API
  • Import is a Post on ProjectExport using the Admin API 

Admin CLI

The Admin CLI provides a command line interface to the Admin API.  The liveapicreator-admin-cli enables you to use command-line commands to manage your API definitions.  (Note: liveapicreator-admin-cli is a NodeJS application, packaged so it operates from the command line).

Node SDK

The Node SDK simplifies API Access for NodeJS apps, with services to make Auth IDs transparent, etc.  This enables you to write Node apps that can be employed in DevOp scripts to manage your API definitions.  A simple example is illustrated below.


Scripting with curl

You can script the import process using Curl as shown below.  The example below can easily be extended to automate the setting of the database properties and and the authentication provider after import.  The project can also be exported from the command line using a GET with a filter.

Get an Auth Token 

You'll need an Auth Token (apikey) for the admin project. You'll use the same username and password that you use to log into the API Creator. The URL will depend on your setup -- here we use the Jetty eval server, you'll need to 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 API key (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 apikey from above:

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

Note we are posting to the  ProjectExport resource, described above.

Scripting with the Admin CLI

The following script creates the Business to Business sample, which consists of 2 APIs including loadable libraries and Custom Authorization Providers.  This is a good example of one approach to deploying a system from source control artifacts.

 

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

and, the 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

Scripting with Node

Node applications can be configured 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.  This information shows how to build a node app you can invoke from the command line to do this.

Overview

Recall that the Admin API includes a Resource called ProjectExport (project is an older name for API), 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 code is shown below.  It was developed to run with the Jetty install of the B2B Demo.  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



Execution Instructions

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
In addition, note that 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).