API Creation by REST

When you use API Creator, you are making REST calls to API Server by way of the admin REST API account. You can also make the REST calls directly. The information in this article is an example of how you can create a new API using the REST API.

Prerequisite: Determine the URL you should be talking to. You should use whatever you use in the Server field when you log in to Live API Creator.

Tip: You can mask some of the raw REST calls for you using the Admin Command Line Interface (CLI). For more information about interacting with your API project using the Admin CLI, see API Creation by Command Line.

How to Create an API

The admin API is a REST API just like any other REST API you create using API Creator.

For more information about auth tokens, see Auth Tokens and Authentication.

Use the following process to create the API:

  1. Obtain an auth token.
  2. Get your basic information.
  3. Create a new API.
  4. Create a database connection.
  5. Verify the API.

This example workflow uses the following URL:

https://api.acme.com

Obtain an Auth Token

Obtain an auth token by POSTing your 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"
}

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

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

Create a new API using 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 project, the auth token, and some roles are created. The API project's URL name is myapi and its ident is 2033.

Create a Database Connection

Connect the API project 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
}

If the parameters are correct, 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 is salted using a random string, then encrypted 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.

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.

Important! Change the default password or delete these users before you use this new API.

Get the Auth Token for the New API

Get an auth token for the new API by issuing 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"
}

This apikey is the auth token for the new API.

You now have the following APIs:

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

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're 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 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 the following:
Screenshot of Chrome debugger

Subpages (1): API Creation by cURL