Docs‎ > ‎Admin API Reference‎ > ‎

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 this page.

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's 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 screen shot, below).
e.g "href": "https://api.acme.com/rest/acme/myproject/v1/@tables/customer"

Response:
[
  {
    "@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 RESTlab:




@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 end point is provided to authenticate a user and obtain an APIKey.


@procedures[/procedure_name]

This call returns metadata about stored procedures - the option procname will retrieve details about the procedure itself.



You will get a response that looks like:

[
  {
    "@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, which will give you something like:

{
  "@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 wil return 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, e.g.:

{
  "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

[
  {
    "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 will return a Swagger document about the API, or using the path - the details for the object.

{
  "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, e.g.:

[
  {
    "@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]

Get a list of foreign keys for a table, or between two tables.

[
  {
    "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, e.g.:

[
  {
    "@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

Passing in the ident of a specific authentication provider will return the detail configuration values for this plugin identity manager.

@login_info

This will return the default values used by authentication provider to create a login dialog.

@apps[/appid]

Return a list of the application and definitions (table settings and skins) for this appid listed.

[
  {
    "@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.

GET https://api.acme.com/rest/default/demo/v1/@license

Without an auth token, it returns something like:

{
  "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, it returns something like:

{
  "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

This call:

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

will return 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 will return a list of the API options for the current API, along with their name and value.

GET https://api.acme.com/rest/default/myproj/v1/@apioptions

will result in the following response:

{
  "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).


Using NodeJS Command Line Script 

You can use the command line utilities (NodeJS) to script the meta tag information (see the attached file showmetatags.sh for a more complete list)
#! /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
ċ
showmetatags.sh
(1k)
Unknown user,
Jan 25, 2016, 1:23 PM