Skip to main content
Previous sectionNext section

Source Code File REST API Tutorial

This chapter provides a brief tutorial that demonstrates how to use the InterSystems IRIS® Source Code File REST API by a series of examples. It contains the following sections:

API Basics

The API used by Atelier to access InterSystems IRIS source code files uses the REST architectural style. REST is named from “Representational State Transfer.” The InterSystems IRIS Source Code File 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:

  • HTTP method—which is one of the following: GET, POST, PUT, DELETE, or HEAD.

  • HTTP headers—provide context information for the call. The HEADERS used in this API include:

    • Authorization, which provides access to the server. Unless you have installed your server with minimal security, you need to provide a username and password to access the API.

    • Content-Type application/json, which specifies that the inbound payload is provided in JSON. You must specify this header for all POST and PUT methods.

    • If-None-Match, which allows a GetDoc or PutDoc call to check if the source code file was modified since it was last accessed.

  • URL—The URL consists of the following parts:

    • http://

    • server-name:port-number/—In this chapter, we assume that InterSystems IRIS is running on the local server and is using port 52773.

    • api/atelier/—This is defined by the web application that has the %Api.Atelier dispatch class.

    • URL part that identifies the method and target. This part can include fixed text and text that you specify to identify the namespace, document name, or type.

    For example, the URL part that identifies the GetDocNames method is v1/namespace/docnames/. The complete URL for this method getting the documents from the MYNS namespace would be:

    http://localhost:52773/api/atelier/v1/MYNS/docnames

    The URL part that identifies the GetServer method is an empty string, so the complete URL for GetServer is:

    http://localhost:52773/api/atelier/

  • URL parameters—modifies the call. If the API method has URL parameters, they are described in the reference section.

  • Inbound JSON payload—format of the inbound message for POST and PUT methods.

  • Outbound JSON payload—format of the outbound message returned by the HTTP method.

Getting Information about the InterSystems IRIS Server

Typically, the first REST call you’ll make is to the GetServer method, which returns information about the InterSystems IRIS Source Code File REST API version number and the namespaces available on the server.

GET http://localhost:52773/api/atelier/
Copy code to clipboard

This call returns the following JSON message:

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": {
      "version": "IRIS for Windows (x86-64) 2018.1.1 (Build 515U) Mon Feb 5 2018 08:24:13 EST",
      "id": "98E1697E-13F9-4D6A-8B73-827873D1D61C",
      "api": 2,
      "features": [
...
      ],
      "namespaces": [
        "%SYS",
        "USER"
      ]
    }
    }
}
Copy code to clipboard

All InterSystems IRIS Source Code File REST API methods that return JSON messages use the same general format:

  • status errors—typically the InterSystems IRIS Source Code File REST API returns errors as HTTP status codes. This field is used under some unusual conditions and this element contains the InterSystems IRIS %Status value, which may contain the text for multiple errors.

  • status summary—contains a summary of the status errors.

  • console—contains the text that InterSystems IRIS would display on the console for this operation.

  • result—contains the results of the method.

The GetServer method returns information about the server in the “result” element. The result element contains one value “content”, which contains:

  • version—contains the version string of the instance of InterSystems IRIS running on the server.

  • id—contains the instance GUID of InterSystems IRIS.

  • api—specifies the version number of the InterSystems IRIS Source Code File REST API implemented in this version of InterSystems IRIS.

  • features—indicates the features that are enabled on this instance.

  • namespaces—lists the namespaces defined on the InterSystems IRIS server.

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:

  • First you get the names of the files with the GetDocNames method.

  • Then you get the contents of one file with the GetDoc method or you can get the contents of multiple files with the GetDocs method.

  • If you want to improve the network efficiency of your application, you can keep a local cache of the names and contents of the source code files and use the GetModifiedDocNames method to get only the names of the source code files whose contents have changed or use the GetDoc method with the If-None-Match HTTP header.

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": "%Api.DocDB.cls",
        "cat": "CLS",
        "ts": "2016-08-03 20:01:42.000",
        "upd": true,
        "db": "IRISLIB",
        "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
      }
    ]
  }
}
Copy code to clipboard

The following GetDoc call returns the contents of the xyz.mac file:

http://localhost:52773/api/atelier/v1/INVENTORY/doc/xyz.mac
Copy code to clipboard

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\""
    ]
  }
}
Copy code to clipboard

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. If you are updating a new file, you must specify either the HTTP header If-None-Match to identify the current version of the file or the ?ignoreConflict=1 URL parameter to bypass version checking. See PutDoc in the reference section for details.

PUT http://localhost:52773/api/atelier/v1/INVENTORY/doc/xyz.mac
Copy code to clipboard

You should specify the Content-Type application/json and the following JSON message:

{
 "enc": false,
 "content": [
   "ROUTINE xyz",
   "xyz ;",
   "   w \"hello\""
   ]
}
Copy code to clipboard

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": []
  }
}
Copy code to clipboard

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:52773/api/atelier/v1/INVENTORY/action/compile
Copy code to clipboard

with the following JSON message:

["xyz.mac"]
Copy code to clipboard

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": []
  }
}
Copy code to clipboard

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:52773/api/atelier/v1/INVENTORY/doc/xyz.mac
Copy code to clipboard

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": []
  }
}
Copy code to clipboard

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 InterSystems IRIS database. For example, if your application wants to present the user with a list of InterSystems IRIS roles, it can discover them with the following call:

POST http://localhost:52773/api/atelier/v1/%25SYS/action/query
Copy code to clipboard

With the SQL query specified in the incoming JSON message:

{"query": "SELECT ID,Description FROM Security.Roles"}
Copy code to clipboard

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"
      }
    ]
  }
}
Copy code to clipboard

You can use the Query method to query any table in InterSystems IRIS. For example, the following call queries a table named Sample.Person in a namespace named SAMPLES.

POST http://localhost:52773/api/atelier/v1/SAMPLES/action/query
{"query": "SELECT Age,SSN,Home_City,Name FROM Sample.Person WHERE Age = 25"}
Copy code to clipboard

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."
      }
    ]
  }
}
Copy code to clipboard