Create a New API with REST

When you use the API Creator in a browser, you are making REST calls to the API Server using the admin REST API account. Therefore, everything you can do in the API Creator, you can also do using REST calls. The following is an example of how you can create a new API using the REST API.

Tip: You can mask some of the raw REST calls for you using a command line utility (CLI). For more information about installing and using the admin CLI, see Install and Use the Admin Command Line Interface.

Prerequisite: Determine which URL you should be talking to by looking at the API Creator. In the following examples, instead of using https://api.acme.com, you can use whatever you use in the Server field when you log in.

Step 1: Obtain an Auth Token

The Admin API is a REST API just like any other REST API you create with Live API Creator. This is because, quite literally, the product is written using itself.

For more information about the Admin API, see Admin API Reference.

To get an auth token, POST the credentials:
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"
}

From now on, we'll assume that we include this auth token in every request as an HTTP header:
Authorization: CALiveAPICreator 3dc5388a87990211d38e31aa674733ce:1

Step 2: Get the Information you need to Create the API

Live API Creator supports multi-tenant installations. You will need to know your account number first.

The following URL retrieves the information you need to create the API:
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.

Get the authentication provider by following the link whose role is authprovidersList:
GET https://api.acme.com/rest/abl/admin/v2/admin:authproviders?sysfilter=equal(account_ident:1708)

The following response is expected:
[
  {
    "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.

Step 3: Create a New API Project

The following URL along with the request payload creates the new API project:
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 POST call returns a status of 201 and the new API is created. Its URL name is myapi, and its ident is 2033. Several other objects were created, such as an auth token and some roles.

Step 4: Create a Database Connection

The following URL along with the request payload connects the API to a database:
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...

The database password has not been stored in the clear. The password has been salted using a random string, then encrypted using a strong encryption algorithm.

Note: You can specify your own key at the container level.

The following URL provides a valid value for dbasetype_ident:
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.

You have connected to the database and created a new API. The API includes user "demo" and a user "guest", both with a default password "Password1". Important! Change this password or delete these users before you use this new API.

Important! You have created two different APIs:

 https://api.acme.com/rest/abl/admin/v2/...The Admin API - Used to query and manipulate APIs, database connections, resources, rules, etc.
 https://api.acme.com/rest/acme/myapi/v1/...The new API - Used to query and manipulate data in your database (customers and orders, in this example)

Step 5: Verify the New API

The following URL along with the payload gets an auth token for the new API:
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 HTTP header will use the new auth token:

Authorization: CALiveAPICreator b1226e0cb79b301eb947ece897326a2e:1

The following URL ensures that the database schema was properly read (the details will depend on your database schema):
GET https://api.acme.com/rest/acme/myapi/v1/@tables

A list of the default endpoints, created from the database schema, are returned:
[
  {
    "@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...

The following URL retrieves some customers:
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 the API Creator is doing, a great way to peek under the hood is to look at what network calls the browser is making. For instance, on Chrome, creating a new resource results in:
Screenshot of Chrome debugger