GetDoc

This method returns the text for the named source code file and namespace.

Return content will contain a source code file object.

Errors pertaining to the source code file will be in the status property of the source code file object. If source control hooks are enabled for the namespace any console output generated by the hook will be captured and returned as an array of lines in the 'console' array.

The result contains the name of the requested file, the database where it is stored, its timestamp, and its category abbreviation (CLS = class; RTN = routine; CSP = CSP file [not recommended for use with InterSystems IRIS]; OTH = other), as well as the source code file contents which are returned in an array.

For text files this will be an array of strings and the 'enc' json field will be set to false.
For binary files this will be an array of base64 encoded chunks and the 'enc' field will be set to true.

Version 2 GetDoc can return the file contents in UDL format (the default), XML format, or the format used by the legacy %RO export utility.

For an example and additional details, refer to Getting the Source Code Files Defined in a Namespace.

URL

GET https://<baseURL>/api/atelier/v1/namespace/doc/doc-name

GET https://<baseURL>/api/atelier/v2/namespace/doc/doc-name

Where <baseURL> is the base URL for your instance.

Note:

If you are getting a CSP file (not recommended for use with InterSystems IRIS), the value of doc-name includes the / (slash) character. This is the reason that the URLMap defining GetDoc contains a (.*) for this parameter name instead of :docname. See Creating the URL Map for REST for details.

URL Parameters

The URL parameter ?binary=1 can be passed to force the source code file to be encoded as binary.
The URL parameter ?storageOnly=1 can be passed to return only the storage portion of a class.
In version 2, the URL parameter ?format= parameter can be passed to specify that the contents of the file should be returned in UDL format (the default), XML format, or the format used by the legacy %RO export utility.
- ?format=udl
- ?format=xml
- ?format=%RO
If you specify ?binary=1, GetDoc ignores the format parameter.

HTTP Headers

If-None-Match—Specify the value returned in the HTTP ETAG header from the previous call to GetDoc or PutDoc for this file. If the file has not changed since the previous call, GetDoc returns the HTTP 304 status.

JSON Messages

The following is an example of the first part of the result returned by requesting %Api.DocDB.cls:

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "%Api.DocDB.cls",
    "db": "IRISLIB",
    "ts": "2016-09-13 22:31:24.000",
    "upd": true,
    "cat": "CLS",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": [
       /// Routing class for the DocDB REST services",
       "Class %Api.DocDB Extends %DocDB.REST",
       "{",
...

The following is the result of the same request with ?binary=1:

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "%Api.DocDB.cls",
    "db": "IRISLIB",
    "ts": "2016-01-04 14:00:04.000",
    "cat": "CLS",
    "status": "",
    "enc": true,
    "content": [
      "Ly8vIFRoaXMgY2xhc3MgaXMgdGhlIHN1cGVyY2xhc3MgZm9yIGFsbCBl  ... PSAzIF0KewoKfQo="
    ]
  }
}

HTTP Return Codes

HTTP 200 if OK.
HTTP 304 if the source code file has not been modified (see https://en.wikipedia.org/wiki/HTTP_ETag).
HTTP 400 if the named resource is not a valid source code file name.
HTTP 404 if the source code file does not exist.
HTTP 500 if an unexpected error occurred (details will be in status error array).

If a 'soft' error occurs such as a 'source code file does not exist', additional information can be found in the 'status' field of the result. Examples of other soft errors include 'file is locked'. For example, the following could be returned with an HTTP 404 return code:

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz1.mac",
    "db": "",
    "ts": "",
    "cat": "RTN",
    "enc": false,
    "content": "",
    "status": "ERROR #16005: Document 'xyz1.mac' does NOT exist"
  }
}

DeleteDoc

PutDoc