API Creation by REST

You can script the import process using cURL, which creates an API. 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 API from the CLI using a GET with a filter.
lac31
When you use API Creator, you are making REST calls to API Server by way of the CA Live API Creator Admin project API (Admin API). The Admin API is a REST API just like any other REST API you create using API Creator. Use this API to query and manipulate APIs, database connections, resources, and rules. You can also make the REST calls directly to API Server. This article illustrates how you can create a new API using the Admin API.
You can mask some of the raw REST calls using the Admin Command Line Interface (CLI).
For more information about interacting with your API using the Admin CLI, see API Creation by Command Line.
You can interact with your API using any REST-compatible tool and language, such as cURL or your web browser. While cURL access is powerful, it is tedious to remember and supply the HTTP Header information (such as the auth token) and the IDs of various objects.
In this article:
2
How to Create an API using REST
Use the following process to create the API:
Verify the Prerequisites
Before creating an API using REST, determine the URL you should be talking to. You should use whatever you use in the Server field when you log in to 
CA Live API Creator
.
Obtain an Auth Token
Obtain an auth token by POSTing your credentials, for example:
POST https://api.acme.com/rest/abl/admin/v2/@authentication { "username": "admin", "password": "Password1" }
The following response is expected:
{ "apikey": "3dc5388a87990211d38e31aa674733ce", "expiration": "2015-12-03T00:54:54.170Z" }
The HTTP header uses the auth token for the new API:
Authorization: CALiveAPICreator b1226e0cb79b301eb947ece897326a2e:1
You include this auth token in every request as an HTTP header:
Authorization: CALiveAPICreator 3dc5388a87990211d38e31aa674733ce:1
Get your Basic Information
Retrieve your Account Number
CA Live API Creator
 supports multi-tenant installations, therefore, you need to know your account number.
Retrieve your account number using the following call:
GET https://api.acme.com/rest/abl/admin/v2/accounts
The following response is expected:
[
{
"ident": 1708,
"ts": "2015-10-29T10:46:31.979282Z",
"name": "Acme account",
"url_name": "acme",
"status": "A",
"public_key": null,
"private_key": null,
"@metadata": {
"href": "https://api.acme.com/rest/abl/admin/v2/admin:accounts/1708",
"checksum": "A:cce2b1e2975e2916",
"links": [
{
"href": "https://api.acme.com/rest/abl/admin/v2/admin:logic_libraries?sysfilter=equal(account_ident:1708)",
"rel": "children",
"role": "logic_librariesList",
"type": "http://www.espressologic.com/model/admin:logic_libraries"
},
{
"href": "https://api.acme.com/rest/abl/admin/v2/admin:authproviders?sysfilter=equal(account_ident:1708)",
"rel": "children",
"role": "authprovidersList",
"type": "http://www.espressologic.com/model/admin:authproviders"
},
etc...
The account 
ident
 is 1708 and its 
url_name
 is acme.
Retrieve your Authentication Provider
Follow the link whose role is 
authprovidersList
 in the previous response:
GET https://api.acme.com/rest/abl/admin/v2/admin:authproviders?sysfilter=equal(account_ident:1708)
The following response is expected, with a single object:
[ { "ident": 1666, "ts": "2015-10-29T10:46:31.981353Z", "name": "Built-in authentication", "comments": null, "auth_type_ident": 1, "class_name": "com.kahuna.server.auth.db.DefaultAuthProvider", "bootstrap_config_value": null, "class_location": "", "param_map": "datasource=AdminDB", "account_ident": 1000, "@metadata": { "href": "https://api.acme.com/rest/abl/admin/v2/admin:authproviders/1666", etc...
The authentication provider's 
ident
 is 1666.
Create a New API
Use the following call:
POST https://api.acme.com/rest/abl/admin/v2/admin:projects { "name": "My new API", "url_name": "myapi", "is_active": true, "account_ident": 1708, "authprovider_ident": 1666 }
The following response is expected:
{ "statusCode": 201, "txsummary": [ { "ident": 2033, "ts": "2015-12-01T15:57:46.406481Z", "name": "My new API", "url_name": "myapi", "comments": null, "status": null, "is_active": true, "account_ident": 1708, "authprovider_ident": 1666 "@metadata": { "href": "https://api.acme.com/rest/abl/admin/v2/admin:projects/2033", "resource": "admin:projects", "verb": "INSERT", etc...
The new API, the auth token, and some roles are created. The API's URL name is 
myapi
 and its 
ident
 is 2033.
Connect an API to a Database
Connect your API to a database using the following call:
POST https://api.acme.com/rest/abl/admin/v2/admin:dbaseschemas { "prefix": "cust", "name": "Customer database", "url": "jdbc:mysql://dbserver.acme.com:3306/customers", "catalog_name": "customers", "user_name": "cust_app", "password": "secret", "active": true, "project_ident": 2033, "dbasetype_ident": 1 }
The following response is expected:
{ "statusCode": 201, "txsummary": [ { "ident": 2032, "ts": "2015-12-01T16:13:16.472265Z", "conn_type": null, "prefix": "cust", "name": "Customer database", "comments": null, "datasource_name": null, "url": "jdbc:mysql://localhost:3306/test", "catalog_name": "test", "schema_name": null, "user_name": "abl", "password": "2:ApOA/E3Th8nzAh+6v6Gb/NktiuGNnvH2Z6fzvLIno8OnunxZsllVbg==", "salt": "+qVMK0PpfE/VgU+IQZJb8vjGV1L4+VvMUvnvicEv", "port_num": null, "read_only": null, "schema_editable": null, "admin_url": null, "active": true, "status": null, "project_ident": 2033, "dbasetype_ident": 1, "@metadata": { "href": "https://api.acme.com/rest/abl/admin/v2/admin:dbaseschemas/2032", "resource": "admin:dbaseschemas", "verb": "INSERT", "links": [ etc...
 
CA Live API Creator
 salts the database password using a random string and encrypts it using a strong encryption algorithm (you can specify our own key at the container level).
By default, the "demo" user and the "guest" user is created, both with 
Password1
 as the default password.
For more information about how your database information is protected, see Security.
Find the Values for dbasetype_ident
You can find the valid values you can provide for 
dbasetype_ident
 by issuing the following call:
GET https://api.acme.com/rest/abl/admin/v2/admin:dbasetypes
The following response is expected:
[ { "ident": 1, "ts": "2015-10-29T10:46:31.858488Z", "name": "MySQL", "description": "MySQL Database", "version_name": "All versions", "driver_class_name_list": "org.mariadb.jdbc.Driver,com.mysql.jdbc.Driver", "catalog_term": "Database", "schema_term": null, "url_prototype": "jdbc:mysql://<host>:<port>/<database>", "driver_help": null, "@metadata": { "href": "https://api.acme.com/rest/abl/admin/v2/admin:dbasetypes/1", "checksum": "A:b80a746d15e6a187" } }, { "ident": 2, "ts": "2015-10-29T10:46:31.858488Z", "name": "Oracle", etc...
You can choose the 
ident
 of the desired database type.
 Verify the API
Prerequisite: You have successfully connected to the database and the default API is in place.
Change the default password or delete these users before you use this new API.
Get the Auth Token for the New API
Issue the following call:
POST https://api.acme.com/rest/acme/myapi/v1/@authentication
{
"username": "demo",
"password": "Password1"
}
The following response is expected:
{
"apikey": "b1226e0cb79b301eb947ece897326a2e",
"expiration": "2015-12-03T00:54:54.170Z"
}
The 
apikey
 is the auth token for the new API.
You now have the following APIs:
  • The Admin API:
    https://api.acme.com/rest/abl/admin/v2/...
  • The new API. Use this API to query and manipulate data in your database (customers and orders in our example).
    https://api.acme.com/rest/acme/myapi/v1/...
If you get a puzzling error (most likely an authentication error, since the auth token for one API cannot not work in a different API), check your URL and make sure you are talking to the correct API.
The HTTP header uses the auth token for the new API:
Authorization: CALiveAPICreator b1226e0cb79b301eb947ece897326a2e:1
Verify that the Database Schema was Properly Read
The details depend on your database schema. Issue the following call:
GET https://api.acme.com/rest/acme/myapi/v1/@tables
A list of the default endpoints is returned, created from the database schema:
[ { "@metadata": { "href": "https://api.acme.com/rest/default/myapi/v1/@tables/cust:customers" }, "prefix": "cust", "entity": "customers", "name": "cust:customers" }, { "@metadata": { "href": "https://api.acme.com/rest/default/myapi/v1/@tables/cust:orders" }, "prefix": "cust", "entity": "orders", "name": "cust:orders" }, etc...
Retrieve Customers
You can retrieve customers by issuing the following call:
GET https://api.acme.com/rest/acme/myapi/v1/cust:customers
The following response is expected:
[ { "cust_no": 54321, "name": "Jones Inc", "balance": 1234.56, "city": "Anytown", "@metadata": { "href": "https://api.acme.com/rest/acme/myapi/v1/cust:customers/54321", "checksum": "A:9dc29d18f94b803c", "links": [] } }, etc...
Tips and Tricks
If you want to do something that API Creator is doing, a great way to peek under the hood is to look at what network calls the browser is making. For example, the following image shows the results for creating a new resource on Chrome:
  CA Technologies  
How to Create an API using cURL
You can script the import process using cURL, which creates an API. 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 API from the CLI using a GET with a filter.
Use the following process to create the API:
  1. Get your basic information.
  2. Create a new API.
  3. Create a database connection.
  4. Verify the API.
Obtain an Auth Token
The Admin API requires an auth token. Use the same username and password that you use to log in to the API Creator. The URL you use depends on your setup. In this example, we use the Jetty eval server. Change that if you use your own server.
The URI might be https. You can find the URI using the REST Lab.
Issue the following command:
curl -H "Content-Type: application/json" -d '{"username": "admin", "password": "Password1"}' -X POST http://localhost:8080/rest/abl/admin/v2/@authentication
The following response is expected:
{ "apikey": "
e315ecb50cae07c799cfdc7a2567db4e
", "expiration": "2016-01-05", "lastLoginTs": "2016-01-06", "lastLoginIP": "123.321.12.21" }
The response includes the auth token, in bold.
Import the API
Prerequisites:
 
  • You have an exported JSON file. For demonstration purposes, the following code snippet uses the example 
    myExport.json
     JSON file as the previously exported file.
  • You have obtained the auth token.
Import your previously exported file as a new API use the following command, including the auth token and the JSON file name:
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
A POST is made to the 
ProjectExport
 resource.