Accessing Caché Source Code Files Using REST
Atelier REST API Tutorial
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter provides a brief tutorial that demonstrates how to use the Atelier REST API by a series of examples. It contains the following sections:

API Basics
The API used by Atelier to access Caché source code files uses the REST architectural style. REST is named from “Representational State Transfer.” The Atelier REST API, like many REST APIs, uses the HTTP GET, POST, PUT, DELETE, and HEAD methods and uses JSON for incoming and outgoing message bodies.
To call an API method, you need to know the following:
Getting Information about the Caché Server
Typically, the first REST call you’ll make is to the GetServer method, which returns information about the Atelier REST API version number and the namespaces available on the server.
GET http://localhost:57772/api/atelier/
This call returns the following JSON message:
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": {
      "version": "Cache for Windows (x86-64) 2016.2 (Build 712U) Wed Aug 3 2016 20:14:04 EDT",
      "id": "FED83556-81D1-499E-9FD6-4232AF1D881E",
      "api": 1,
      "features": [
        {
          "name": "DEEPSEE",
          "enabled": true
        },
        {
          "name": "ENSEMBLE",
          "enabled": true
        },
        {
          "name": "HEALTHSHARE",
          "enabled": false
        }
      ],
      "namespaces": [
        "%SYS",
        "DOCBOOK",
        "ENSDEMO",
        "ENSEMBLE",
        "INVENTORY",
        "SAMPLES",
        "USER"
      ]
    }
  }
}
All Atelier REST API methods that return JSON messages use the same general format:
The GetServer method returns information about the server in the “result” element. The result element contains one value “content”, which contains:
The GetNamespace method returns information about the specified namespace, including the databases that are mapped to the namespace and a hash for each database. The hash is useful for improving efficiency of communication with the server. But you can get the information about the source code files in the namespace with just the namespace information returned by GetServer.
Getting the Source Code Files Defined in a Namespace
To get the information about the source code files in a namespace:
The GetDocNames method returns the names of all of the source code files in all databases mapped to the namespace.
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "name": "%Activate.Enum.cls",
        "cat": "CLS",
        "ts": "2016-08-03 20:01:42.000",
        "upd": true,
        "db": "CACHELIB",
        "gen": false
      },
      ...
      {
        "name": "EnsProfile.mac",
        "cat": "RTN",
        "ts": "2003-09-19 13:53:31.000",
        "upd": true,
        "db": "INVENTORYR",
        "gen": false
      },
      ...
      {
        "name": "xyz.mac",
        "cat": "RTN",
        "ts": "2016-08-11 15:05:02.167",
        "upd": false,
        "db": "INVENTORYR",
        "gen": false
      }
    ]
  }
}
The following GetDoc call returns the contents of the xyz.mac file:
http://localhost:57772/api/atelier/v1/INVENTORY/doc/xyz.mac
This call returns:
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz.mac",
    "db": "INVENTORYR",
    "ts": "2016-09-14 14:10:16.540",
    "upd": false,
    "cat": "RTN",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": [
      "ROUTINE xyz",
      "xyz ;",
      "   w \"hello\""
    ]
  }
}
Creating a New File in a Namespace or Updating an Existing File
To create a new file in a namespace or update an existing file, you use the PutDoc method. For example, the following REST call creates a new xyz.mac source code file in the INVENTORY namespace or, if the xyz.mac file exists, this call replaces the original definition of the file with the new one.
PUT http://localhost:57772/api/atelier/v1/INVENTORY/doc/xyz.mac
You should specify the Content-Type application/json and the following JSON message:
{
 "enc": false,
 "content": [
   "ROUTINE xyz",
   "xyz ;",
   "   w \"hello\""
   ]
}
The call returns the following JSON message. It shows that the source code file has been created in the INVENTORYR database, which is the default database for routines in the INVENTORY namespace.
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz.mac",
    "db": "INVENTORYR",
    "ts": "2016-09-14 14:10:16.540",
    "upd": false,
    "cat": "RTN",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": []
  }
}
If you are updating or creating a binary file, specify a true value for enc and include the binary contents as an array of blocks of the base64 encoding of the binary value.
Compiling a File
The Compile method compiles the source code files specified by name in the incoming JSON array. For example, to compile xyz.mac, POST the following:
http://localhost:57772/api/atelier/v1/INVENTORY/action/compile
with the following JSON message:
["xyz.mac"]
The method returns:
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [
    "",
    "Compilation started on 08/14/2016 15:25:20 with qualifiers 'cuk'",
    "xyz.int is up to date. Compile of this item skipped.",
    "Compilation finished successfully in 0.008s."
  ],
  "result": {
    "content": []
  }
}
For some source code files, such as classes, Compile returns storage information in the returned content.
Deleting a File
The DeleteDoc method deletes the file specified in the URL. The DeleteDoc method has the same URL as the GetDoc method except that you use the HTTP Delete method instead of the Get Method. To delete xyz.mac, make an HTTP DELETE request with the URL:
http://localhost:57772/api/atelier/v1/INVENTORY/doc/xyz.mac
The Delete method returns the following JSON message:
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz.mac",
    "db": "INVENTORYR",
    "ts": "",
    "cat": "RTN",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": []
  }
}
When a file has been deleted, the timestamp, ts, has a value of "" (empty string).
Performing an SQL Query
The Query method performs an SQL query on any Caché database. For example, if your application wants to present the user with a list of Caché roles, it can discover them with the following call:
POST http://localhost:57772/api/atelier/v1/%25SYS/action/query
With the SQL query specified in the incoming JSON message:
{"query": "SELECT ID,Description FROM Security.Roles"}
This call returns the results of the SQL query as JSON in the result content element.
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "ID": "%all",
        "Description": "The Super-User Role"
      },
      {
        "ID": "%db_%default",
        "Description": "R/W access for this resource"
      },
      ... 
      {
        "ID": "%sqltunetable",
        "Description": "Role for use by tunetable to sample tables irrespective of row level security"
      }
    ]
  }
}
You can use the Query method to query any table in Caché. The following call queries the SAMPLES Sample.Person database.
POST http://localhost:57772/api/atelier/v1/SAMPLES/action/query
{"query": "SELECT Age,SSN,Home_City,Name FROM Sample.Person WHERE Age = 25"}
This call returns:
{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "Age": 25,
        "SSN": "230-78-7696",
        "Home_City": "Larchmont",
        "Name": "DeLillo,Jose F."
      },
      {
        "Age": 25,
        "SSN": "546-73-7513",
        "Home_City": "Gansevoort",
        "Name": "Klingman,Thelma H."
      }
    ]
  }
}