System REST endpoints

Your API's automatically include a number of special endpoints that allow you to retrieve information about the API, rather than actual data. These are available to users of that API if they have access to Meta Tables.

These endpoints are read-only (except for @authentication), so only GETs are allowed.
If you want to do some real work using the API, like creating new resources, new rules, even new API's, see Create a New API with REST.

All examples here assume that you are sending an auth token along with the request, either in the URL (with the auth parameter) or (more commonly) in the Authorization header. 

Exceptions: @authentication does not require an auth token because that is how you get an auth token. @heartbeat can be called without authentication, @license can also be called without authentication but only returns minimal information.

@tables[/tablename]

In addition, the API key in question must have access to the resource in question. For instance, if you want to get the list of all tables for a project, your API key must have a role with a permission for the @tables pseudo-table.

Example: retrieve a list of all tables in a project

URL:
https://server.acme.com/rest/acme/myproject/v1/@tables

You can use the href URL to retrieve full information for a table, or "*" for full information for all table information (see the following screen shot). For example, "href": "https://api.acme.com/rest/acme/myproject/v1/@tables/customer"

Response
The following response is expected:

[
  {
    "@metadata": {
        "href": "https://api.acme.com/rest/acme/myproject/v1/@tables/customer"
    },
    "name": "customer"
  },
  {
    "@metadata": {
        "href": "https://api.acme.com/rest/acme/myproject/v1/@tables/lineitem"
    },
    "name": "lineitem"
  },
  {
    "@metadata": {
        "href": "https://api.acme.com/rest/acme/myproject/v1/@tables/product"
    },
    "name": "product"
  },
  {
    "@metadata": {
        "href": "https://api.acme.com/rest/acme/myproject/v1/@tables/purchaseorder"
    },
    "name": "purchaseorder"
  }
]

@tables/[tablename]

You can then follow one of the href links, such as https://server.acme.com/rest/acme/myproject/v1/@tables/lineitem

{
  "@metadata": {
    "href": "https://api.acme.com/rest/acme/myproject/v1/@tables/lineitem"
  },
  "name": "lineitem",
  "primaryKey": {
    "columns": [
      {
        "name": "lineitem_id",
        "type": "BIGINT"
      }
    ]
  },
  "columns": [
    {
      "name": "lineitem_id",
      "type": "BIGINT",
      "size": 19,
      "nullable": false
    },
    {
      "name": "product_number",
      "type": "BIGINT",
      "size": 19,
      "nullable": false
    },
    {
      "name": "order_number",
      "type": "BIGINT",
      "size": 19,
      "nullable": false
    },
    {
      "name": "qty_ordered",
      "type": "INTEGER",
      "size": 10,
      "nullable": false
    },
    {
      "name": "product_price",
      "type": "DECIMAL",
      "size": 19,
      "nullable": true
    },
    {
      "name": "amount",
      "type": "DECIMAL",
      "size": 19,
      "nullable": true
    }
  ],
  "parents": [
    {
      "name": "product",
      "parent_table": "product",
      "parent_columns": [
        "product_number"
      ],
      "child_columns": [
        "product_number"
      ]
    },
    {
      "name": "lineitem_purchaseorder",
      "parent_table": "purchaseorder",
      "parent_columns": [
        "order_number"
      ],
      "child_columns": [
        "order_number"
      ]
    }
  ],
  "keys": [
    {
      "name": "PRIMARY",
      "type": "primary",
      "columns": "lineitem_id"
    }
  ]
}

You can test Admin APIs in the REST Lab:

@resources[/ident]

The system provides similar built-in resources for resources.  The href will provide a link to retrieve details about the specific resource.

https://api.acme.com/rest/acme/myproject/v1/@resources

[
  {
    "@metadata": {
      "href": "http://api.acme.com/rest/acme/myproject/v1/@resources/2099"
    },
    "ident": 2099,
    "name": "ProfileAccounts",
    "apiVersion": "v1",
    "description": null,
    "resource_type": "NORMAL"
  }
]

@view[/view_name]

A REST call to get all views for the current project. This will return a list of all views for the selected project id.  By adding a view name (found in the href of the metadata) you can retrieve details about the view itself.
https://api.acme.com/rest/acme/demo/v1/@views?projectId=1234

@authentication

A RESTful endpoint is provided to authenticate a user and obtain an APIKey.

@procedures[/procedure_name]

This call returns metadata about stored procedures. The option procname retrieves details about the procedure itself.

https://api.acme.com/rest/acme/demo/v1/@procedures?projectId=1234

The following response is expected:

[
  {
    "@metadata": {
      "href": "https://api.acme.com/rest/acme/demo/v1/@procedures/demo:get_employee?projectId=1234"
    },
    "prefix": "demo",
    "entity": "get_employee",
    "name": "demo:get_employee"
  },
  {
    "@metadata": {
      "href": "https://api.acme.com/rest/acme/demo/v1/@procedures/demo:promote_employee?projectId=1234"
    },
    "prefix": "demo",
    "entity": "promote_employee",
    "name": "demo:promote_employee"
  }
]


@procedure[procedure_name]

You can then get full information on a procedure by doing a GET against that procedure's URL. For example, the call returns the following information:

{
  "@metadata": {
    "href": "https://api.acme.com/rest/acme/demo/v1/@procedures/demo:get_employee?projectId=1234"
  },
  "prefix": "demo",
  "entity": "get_employee",
  "name": "demo:get_employee",
  "args": [
    {
      "name": "given_employee_id",
      "type": "BIGINT",
      "direction": "IN"
    },
    {
      "name": "plus_one",
      "type": "BIGINT",
      "direction": "IN_OUT"
    }
  ]
}

@sequences

This call returns a list of all the database sequences in use. This call returns an empty array except for those databases that support sequences (like Oracle).

@perf

This call returns an object containing pointers to the various kinds of performance statistics available. (found on the metrics tab and sub-tabs).

@perf[[rules | sql | adminSql] [?projectId-2000]

{
  "meta": {
    "currentTime": 42132335320569
  },
  "stats": [
    {
      "rule": {
        "ident": 2000,
        "entity": "demo:customer",
        "type": "validation",
        "name": "Validation return row.balance <= row.credit_limit;"
      },
      "firstExecutionTime": 37501167023156,
      "lastExecutionTime": 37501167023156,
      "shortestExecutionTime": 1585839,
      "longestExecutionTime": 1585839,
      "numberOfExecutions": 1,
      "totalExecutionTime": 1585839
    },
    {
      "rule": {
        "ident": 2002,
        "entity": "demo:customer",
        "type": "sum",
        "name": "Derive balance as sum(PurchaseOrderList.amount_total where paid = false)"
      },
      "firstExecutionTime": 37501164919658,
      "lastExecutionTime": 37501164919658,
      "shortestExecutionTime": 1437219,
      "longestExecutionTime": 1437219,
      "numberOfExecutions": 1,
      "totalExecutionTime": 1437219
    },
    {
      "rule": {
        "ident": 2005,
        "entity": "demo:PurchaseOrder",
        "type": "event",
        "name": "Audit Purchase Order amount changes"
      },
      "firstExecutionTime": 37501158809963,
      "lastExecutionTime": 37501158809963,
      "shortestExecutionTime": 10199279,
      "longestExecutionTime": 10199279,
      "numberOfExecutions": 1,
      "totalExecutionTime": 10199279
    }
  ]

@serverinfo

This call returns information about the server it reached, for example:

{
  "publicAddress": "12.34.56.78",
  "hostname": "api.acme.com",
  "osName": "Linux 2.8",
  "currentDateTime": "2015-11-10T01:19:27.539Z",
  "numCores": 8,
  "freeMemory": 263916512,
  "maxMemory": 3817865216,
  "totalMemory": 632291328,
  "uptime": 621827,
  "loadAverage": 2.48974609375,
  "adminSchemaVersion": "20151106",
  "serverVersion": "2.0"
}

@dependencies

This call returns dependencies information, for example:

[
  {
    "tableName": "LOGICDEMO."LineItem"",
    "dependencies": [
      {
        "ruleName": "Discounted price*qty",
        "columnName": "amount",
        "dependsOn": "product_price"
      },
      {
        "ruleName": "Discounted price*qty",
        "columnName": "amount",
        "dependsOn": "qty_ordered"
      },
      {
        "ruleName": "Derive product_price as parentcopy(product.price)",
        "columnName": "product_price",
        "roleName": "product",
        "dependsOn": "price"
      }
    ]
  },  more ....

@docs[/api_object_name]

This call returns a Swagger document about the API. If you use the path, it returns the details for the object. For example:
{
  "swaggerVersion": "1.2",
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "apiVersion": "v1",
  "info": {
    "title": "Northwind",
    "description": "Simple order processing demo"
  },
  "authorizations": {
    "Admin key": {
      "type": "apiKey",
      "passAs": "header",
      "keyname": "Authorization"
    }
  },
  "apis": [
    {
      "path": "/CustomersBusObject",
      "description": "resource"
    },
    {
      "path": "/EmployeesObject",
      "description": "resource"
    },
etc...

@rules[/ident]

This call returns a high-level list of API defined logic rules, for example:
[
  {
    "@metadata": {
      "href": "https://api.acme.com/rest/default/demo/v1/@rules/2000"
    },
    "ident": 2000,
    "bestName": "Validation return row.Balance <= row.CreditLimit;",
    "name": "",
    "entityName": "nw:Customers",
    "columnName": null,
    "comments": "Observe Error message insertion points {}"
  },
  {
    "@metadata": {
      "href": "https://api.acme.com/rest/default/demo/v1/@rules/2001"
    },
    "ident": 2001,
    "bestName": "adjust the balance to be the sum(OrdersList.AmountTotal) for unshipped orders",
    "name": "adjust the balance to be the sum(OrdersList.AmountTotal) for unshipped orders",
    "entityName": "nw:Customers",
    "columnName": null,
    "comments": "Adjusts Balance by *reacting* to changes in OrdersList.AmountTotal,
including other changes noted in Table/Column help."
  },
etc...

@fks?[parentTable=[prefix:]tableName | childTable=[prefix:]tableName]

This call returns a list of foreign keys for a table or between two tables, for example:

[
  {
    "constraint_name": null,
    "parent_table_name": "demo:customer",
    "child_table_name": "demo:PurchaseOrder",
    "child_to_parent_name": "customer",
    "parent_to_child_name": "PurchaseOrderList",
    "parent_columns": [
      "name"
    ],
    "child_columns": [
      "customer_name"
    ]
  },
  {
    "constraint_name": null,
    "parent_table_name": "demo:customer",
    "child_table_name": "sample:orders",
    "child_to_parent_name": "demoCustomer",
    "parent_to_child_name": "sampleOrders",
    "parent_columns": [
      "name"
    ],
    "child_columns": [
      "customer_name"
    ]
  }
]

@metatables

This call returns a list of most of the API's on this page, for example:

[
{
"@metadata": {
"href": "https://api.acme.com/rest/default/demo/v1/@tables"
},
"name": "@tables"
},
{
"@metadata": {
"href": "https://api.acme.com/rest/default/demo/v1/@views"
},
"name": "@views"
},
{
"@metadata": {
"href": "https://api.acme.com/rest/default/demo/v1/@procedures"
},
"name": "@procedures"
},
{
"@metadata": {
"href": "https://api.acme.com/rest/default/demo/v1/@resources"
},
"name": "@resources"
}
]

@auth_provider_info/ident

To return the detail configuration values for this plugin identity manager, pass in the ident of a specific authentication provider.

@login_info

This call returns the default values used by authentication provider to create a login dialog.

@apps[/appid]

This call returns a list of the application and definitions (table settings and skins) for this appid listed, for example:
[
  {
    "@metadata": {
      "href": "http://api.acme.com/rest/default/sample/v1/@apps/2000"
    },
    "ident": 2000,
    "name": "Default app",
    "description": null
  }
]

@license

This call returns a value that depends on whether the call is authenticated (includes an auth token) or not. For example, the following call:
GET https://api.acme.com/rest/default/demo/v1/@license

Without an auth token, returns the following:
{
  "company": "Acme Corp.",
  "organization": "Accounting",
  "location": "New York, NY, USA",
  "license_type": "PRODUCTION",
  "license_expiration": "2017-12-31T23:59:59.999Z"
}

If the call is authenticated, returns the following:
{
  "company": "Acme Corp.",
  "organization": "Accounting",
  "location": "New York, NY, USA",
  "license_type": "PRODUCTION",
  "license_expiration": "2017-12-31T23:59:59.999Z",
  "product_version": "2",
  "max_cores": 8,
  "max_memory": 1024,
  "max_projects": 0,
  "max_requests": 0,
  "max_resources": 0,
  "max_rules": 0,
  "eula": "Lorem ipsum etc..."
}


@heartbeat

The following call:
GET https://api.acme.com/rest/default/demo/v1/@heartbeat

returns the following:
{
  "status": "OK"
}

If the value of status is anything but OK, then the server is not feeling well. Otherwise the server is most likely OK.

@apioptions

This call returns a list of the API options for the current API, along with their name and value. For example, the following call:
GET https://api.acme.com/rest/default/myproj/v1/@apioptions

returns the following:
{
"1": {
"name": "Aggregate Default Override",
"option_value": "false"
},
"2": {
"name": "Type base URI",
"option_value": "urn:caliveapicreator:demo:"
},
"3": {
"name": "HTTPS only",
"option_value": "false"
},
etc...

where the key (1, 2, 3, etc...) is the ID of the option type (the name is the human-readable equivalent).

Script the Meta Tag Information

You can script the meta tag information using the command line utilities (NodeJS). For a complete list, see the attached file showmetatags.sh.
#! /bin/bash

# Uses NodeJS and Live API Creator command line interface
# npm install liveapicreator-cli -g
# Live API Creator meta @ rest endpoints

#echo 1
# Note that the URL contains the entire path to the project 
lac login -u demo -p Password1 http://localhost:8080/APIServer/rest/default/nwindb2b/v1 -a localnw
lac use localnw

#Show the current license info (add --format json) for full EULA
lac get @license

#returns OK if server is up
lac get @heartbeat

# Show All Tables and columns for selected table
lac get @tables
lac get @tables/nw:Customers

# Show All views and columns for selected view
lac get @views
lac get @views/nw:Current%20Product%20List

# Show All Resoures and attribute for selected resources (using ident)
lac get @resources
lac get @resources/2961
# Show All Store Proc and attribute for selected proc (using ident)
lac get @procedures
#lac get @procedures/somename

#Show the performance metrics for sql, rules, and admin SQL (add --format json) for detailed view
lac get @perf --format json
lac get @perf/sql?projectId=2047
lac get @perf/rules?projectId=2047  
lac get @perf/adminSql?projectId=2047 

# Swagger 1.2 doc format
lac get @docs
lac get @docs/nw:Customers

#List of Rules
lac get @rules

#API Project settings
lac get @apioptions

#Information on the default auth provider
lac get @auth_provider_info/1000

#Information from the Auth Provider
lac get @login_info
ċ
Screen Shot 2015-10-22 at 8.16.26 PM.png
(265k)
Laura Carrubba,
Feb 16, 2016, 1:44 PM
ċ
admin data.png
(285k)
Laura Carrubba,
Feb 16, 2016, 1:44 PM
ċ
showmetatags.sh
(1k)
Laura Carrubba,
Feb 16, 2016, 1:44 PM
Comments