Source Code File REST API Reference
This page provides reference information on InterSystems IRIS® data platform Source Code File REST interface.
The endpoints for this API contain the term atelier because this API was developed for use by Atelier, our deprecated Eclipse-based IDE. Our VS Code - ObjectScript IDE now uses the same API.
GetServer
This method returns information about the server, including the Source Code REST API version and namespaces that are available on the server.
For an example and additional details, refer to Getting Information about the InterSystems IRIS Server.
URL
GET https://<baseURL>/api/atelier/
Where <baseURL> is the base URL for your instance.
JSON Messages
The following returned content is a server descriptor:
{
"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"
]
}
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
HeadServer
This method returns the HttpHeader for the server.
URL
HEAD https://<baseURL>/api/atelier/
Where <baseURL> is the base URL for your instance.
JSON Messages
No returned content.
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
GetJobs
This method returns a list of running jobs on the InterSystems IRIS instance.
URL
GET https://<baseURL>/api/atelier/v1/%25SYS/jobs
Where <baseURL> is the base URL for your instance.
Because % is a URL special character, to specify a literal % you must follow it with 25 (the hexadecimal code for the percent character). Therefore, you must use %25SYS to specify the literal %SYS.
JSON Messages
The following returned content is an array of job descriptors:
{
"status": {
"errors": [],
"summary": ""
},
"console": [],
"result": {
"content": [
{
"pid": 1394,
"namespace": "%SYS",
"routine": "%Studio.Debugger.1",
"state": "RUN",
"device": "|TCP|1972|1394"
},
{
"pid": 1345,
"namespace": "%SYS",
"routine": "RECEIVE",
"state": "HANG",
"device": "/dev/null"
},
{
"pid": 1364,
"namespace": "%SYS",
"routine": "%SYS.TaskSuper.1",
"state": "SELECTW",
"device": "/dev/null"
},
{
"pid": 1396,
"namespace": "%SYS",
"routine": "%SYS.cspServer3",
"state": "READ",
"device": "|TCP|1972|1396"
},
{
"pid": 1346,
"namespace": "%SYS",
"routine": "ECPWork",
"state": "RUNW",
"device": "/dev/null"
},
{
"pid": 1417,
"namespace": "%SYS",
"routine": "%SYS.BINDSRV",
"state": "READ",
"device": "|TCP|1972|1417"
}
]
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
GetMetaData
This method returns the binary contents of the METADATA.zip file for the named database. Atelier uses this file to store index information so that it can preserve this information for future sessions.
URL
GET https://<baseURL>/api/atelier/v1/%25SYS/metadata/database
Where <baseURL> is the base URL for your instance.
Because % is a URL special character, to specify a literal % you must follow it with 25 (the hexadecimal code for the percent character). Therefore, you must use %25SYS to specify the literal %SYS.
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 404 if the source code file does not exist.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
GetCSPApps
This method returns a list of web applications defined on the server or defined for a specified namespace on the server.
URL
GET https://<baseURL>/api/atelier/v1/%25SYS/cspapps
GET https://<baseURL>/api/atelier/v1/%25SYS/cspapps/namespace
Where:
The base URL for your instance.
Specifies the name of the namespace. If namespace is not specified, this method returns the web applications for all namespaces.
Because % is a URL special character, to specify a literal % you must follow it with 25 (the hexadecimal code for the percent character). Therefore, you must use %25SYS to specify the literal %SYS.
URL Parameters
The URL parameter ?detail=1 can be passed to return an array containing objects which describe the application in more detail.
JSON Messages
The following returned content is an array listing the defined web applications:
{
"status": {
"errors": [],
"summary": ""
},
"console": [],
"result": {
"content": [
"/csp/broker",
"/csp/documatic",
"/csp/sys",
"/csp/sys/exp",
"/csp/sys/mgr",
"/csp/sys/op",
"/csp/sys/sec",
"/isc/studio/rules",
"/isc/studio/templates",
"/isc/studio/usertemplates",
"/csp/user"
]
}
}
The following is the same returned content with detail=1:
{
"status": {
"errors": [],
"summary": ""
},
"console": [],
"result": {
"content": [
{
"name": "/csp/broker",
"default": false
},
{
"name": "/csp/documatic",
"default": false
},
{
"name": "/csp/sys",
"default": true
},
{
"name": "/csp/sys/exp",
"default": false
},
{
"name": "/csp/sys/mgr",
"default": false
},
{
"name": "/csp/sys/op",
"default": false
},
{
"name": "/csp/sys/sec",
"default": false
},
{
"name": "/isc/studio/rules",
"default": false
},
{
"name": "/isc/studio/templates",
"default": false
},
{
"name": "/isc/studio/usertemplates",
"default": false
},
{
"name": "/csp/user",
"default": true
}
]
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
GetNamespace
This method returns information about a specific namespace.
URL
GET https://<baseURL>/api/atelier/v1/namespace
Where <baseURL> is the base URL for your instance.
JSON Messages
The following is the returned content information about the namespace USER:
{
"status": {
"errors": [],
"summary": ""
},
"console": [],
"result": {
"content": {
"name": "USER",
"db": [
{
"name": "USER",
"crhash": "3A1A0E8B6C8",
"default": true,
"dbsys": false
},
{
"name": "IRISLIB",
"crhash": "A56AAA8D5418",
"default": false,
"dbsys": true
},
{
"name": "IRISLOCALDATA",
"crhash": "3A1A0551876",
"default": false,
"dbsys": false
},
{
"name": "IRISSYS",
"crhash": "3A19FFD2EF0",
"default": false,
"dbsys": true
}
],
"features": [
{
"name": "ENSEMBLE",
"enabled": false
}
]
}
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
GetDocNames
This method returns a list of source code file names. The optional cat and type constrain the types of source code files.
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/docnames
GET https://<baseURL>/api/atelier/v1/namespace/docnames/cat
GET https://<baseURL>/api/atelier/v1/namespace/docnames/cat/type
Where:
The base URL for your instance.
Specifies a category code: CLS = class; RTN = routine; CSP = CSP file (not recommended for use with InterSystems IRIS); OTH = other. Default is *.
Specifies a source code file type. Can be an * wildcard or a file type. For CLS, type must be *. For RTN, type may be mac, int, inc, bas ,mvi, or mvb. For CSP, type can be a list of file types such as js or css separated by commas. Default is *.
URL Parameters
-
The URL parameter 'generated=1' specifies that generated source code files should be included.
-
The URL parameter 'filter' provides a SQL filter that can be used to match the names.
JSON Messages
The following is the returned content, an array of source code file descriptors:
{
"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
}
]
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
GetModifiedDocNames
This method returns a list of source code files that have been modified since the time the databases had the specified hashes. It is passed a list of database keys and hashes as a JSON array. The hash values are used to determine if anything has changed in the database defined by the key. Typically, you first call this api with an empty array as the incoming JSON message. This returns the names of all source code files in the namespace with the database key and hash for each file. Then you can post the dbname and dbhash to discover which source code files have been modified on the server since the last call.
You post the list of source code files to check as shown in the following example:
[ { "dbname" : "USER",
"dbhash" : "KWAGbOdnRblPzANaiv1Oiu0BZLI"
}, ... ]
URL
POST https://<baseURL>/api/atelier/v1/namespace/modified/type
Where:
The base URL for your instance.
Specifies a source code file type as * or a three-letter code, ls, mac, int, inc, bas, or mvi. Default is *.
This call requires the header Content-Type application/json.
JSON Messages
The following is the returned content, an array of source code file descriptors:
[ { "dbname" : "USER",
"dbhash" : "Qx1zuNaulq3b_1yR9ahZAfjkc-",
"crhash" : "47763751EC",
"docs": [{
"name": "User.NewClass1.cls",
"ts": "2016-01-04 14:00:04.000",
"gen": false,
"depl": false
}, ... ]
}, ... ]
If a source code file has been deleted since the specified dbhash, it is returned in the list with a time stamp set to an empty string:
"ts": ""
If a database was included because of mapping and the mapping is removed, both dbhash and crhash are returned with a "000" value and docs is returned as an empty array.
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 400 if the posted content is empty or type is anything other than CLS.
-
HTTP 415 if content type is not application/json.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
PutDoc
This method saves the supplied source code file. If the file does not exist, this method creates it, and, if the file exists, this method replaces the existing file with the one specified. To ensure that you are overwriting the correct version of the file, specify the If-None-Match header with the timestamp value returned in the ETAG header of a previous PutDoc or GetDoc. If you want to overwrite the file without checking the version, specify the ?ignoreConflict=1 URL parameter. This method returns a corresponding source code file object. If you are saving a binary file, set the enc element of the incoming JSON message to true and include the file content as an array of blocks of base64. If the text on the server is changed during the save process (for example by a source control hook) the updated text will be returned in the content array of the returned source code file.
Errors pertaining to the source code file will be in the status property of the returned source code file object.
Version 2 PutDoc has the capability to accept the contents of the file in three formats: the default UDL format, XML format, and the format used by the legacy %RO export utility. PutDoc automatically recognizes the format of the file contents.
For an example and additional details, refer to Creating a New File in a Namespace or Updating an Existing File.
URL and Input JSON Message
PUT https://<baseURL>/api/atelier/v1/namespace/doc/doc-name
PUT https://<baseURL>/api/atelier/v2/namespace/doc/doc-name
Where <baseURL> is the base URL for your instance.
The following is an example of the input JSON message for a PutDoc for the source code file xyz.mac:
{
"enc": false,
"content": [
"ROUTINE xyz",
"xyz ;",
" w \"hello\""
]
}
If you are creating a CSP file (not recommended for InterSystems IRIS), the value of doc-name includes the / (slash) character. This is the reason that the URLMap defining PutDoc contains a (.*) for this parameter name instead of :docname. See Creating the URL Map for REST for details.
URL Parameters
The URL parameter ?ignoreConflict=1 can be passed to bypass ETAG checking. This forces the source code file to be written to the server even if the file has changed since you previously accessed it.
HTTP Headers
-
If-None-Match—To ensure that you are overwriting the correct version of the file, specify the If-None-Match header with the timestamp value returned in the ETAG header of a previous PutDoc or GetDoc.
JSON Messages
The following is the returned content for a PUT of source code file xyz.mac:
{
"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": []
}
}
When a class is saved PutDoc always returns the storage section because it may be normalized by the server. The 'flags' json field will be 1 if the contents is only the storage section. 'flags' will be 0 if PutDoc returns either the entire class in content or if content is empty.
HTTP Return Codes
-
HTTP 200 if updated.
-
HTTP 201 if created.
-
HTTP 400 if the resource name is an invalid source code file name.
-
HTTP 404 if the resource is not found.
-
HTTP 409 if a conflict between server and client versions is detected based on the timestamp. If the file exists, PutDoc returns this code unless the If-None-Match header specifies the current timestamp value of the file on the server. If the conflict exists, the return message includes the contents of the source code file on the server.
-
HTTP 415 if not passed application/json as content type.
-
HTTP 425 if the source code file is locked and cannot be written to.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
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.
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
This method deletes the named source code file in the specified namespace. It returns the corresponding source code file object.
Errors pertaining to the source code file will be in the status property of the source code file object.
For an example and additional details, refer to Deleting a File.
URL
DELETE https://<baseURL>/api/atelier/v1/namespace/doc/doc-name
Where <baseURL> is the base URL for your instance.
If you are deleting 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 DeleteDoc contains a (.*) for this parameter name instead of :docname. See Creating the URL Map for REST for details.
JSON Messages
The following is the returned content for a DELETE of source code file xyz.mac:
{
"status": {
"errors": [],
"summary": ""
},
"console": [],
"result": {
"name": "xyz.mac",
"db": "INVENTORYR",
"ts": "",
"cat": "RTN",
"status": "",
"enc": false,
"flags": 0,
"content": []
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
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 423 if the resource is locked.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
HeadDoc
This method returns the HttpHeader for the named source code file and namespace. This header contains a timestamp which can be used to detect discrepancies between server and client versions.
URL
HEAD https://<baseURL>/api/atelier/v1/namespace/doc/doc-name
Where <baseURL> is the base URL for your instance.
If you are getting the HTTP header for 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 HeadDoc contains a (.*) for this parameter name instead of :docname. See Creating the URL Map for REST for details.
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 400 if the resource name is an invalid source code file name.
-
HTTP 404 if the resource is not found.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
GetDocs
This method returns the text for the all of the specified source code files in the namespace.
URL
POST https://<baseURL>/api/atelier/v1/namespace/docs
Where <baseURL> is the base URL for your instance.
A list of source code files to be fetched is passed in the body of the http request. The request body is a JSON array of names of source code files you want to fetch. For example, [ "%Api.DocDB.cls", ... ].
This call requires the header Content-Type application/json.
JSON Messages
Return content is an array of source code file objects. See GetDoc method for an example of the structure of a source code file object.
Errors pertaining to a source code file will be in the status property of each source code file object. This method does NOT support the storageOnly flag. Neither does it do ETAG checking (and therefore will not return an HTTP 304 under any circumstances).
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 415 if the passed content type is not application/json.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
DeleteDocs
This method deletes a list of named source code files. It returns a corresponding array of source code file objects.
URL
DELETE https://<baseURL>/api/atelier/v1/namespace/docs
Where <baseURL> is the base URL for your instance.
The list of files to delete is passed in the body of the http request as a JSON array. For example, [ "%Api.DocDB.cls", ... ].
This call requires the header Content-Type application/json.
JSON Messages
The following is the returned content for a DELETE of source code file xyz.mac and the nonexistent class notexist.cls:
{
"status": {
"errors": [],
"summary": ""
},
"console": [
],
"result": [
{
"name": "xyz.mac",
"db": "INVENTORYR",
"status": ""
},
{
"name": "notexist.cls",
"db": "",
"status": "ERROR #5001: Document Does Not Exist: User.notexist.cls [zExistsDoc+3^%Atelier.v1.Utils.General.1:%SYS]"
}
]
}
Errors pertaining to a each source code file will be in the status property of each returned source code file object. If the status is an empty string the source code file was deleted successfully. Otherwise the source code file was NOT deleted.
For deleted source code files, the db property will indicate from which database the doc was deleted.
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 400 if the posted data does not contain a JSON array.
-
HTTP 415 if the passed content type is not application/json.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
Compile
This method compiles source code files. It permits the compilation of more than one source code file at a time. It returns an array of corresponding source code file objects.
The list of files to be compiled is passed in the body of the http request as a JSON array. For example, [ "%Api.DocDB.cls", ... ].
For an example and additional details, refer to Compiling a File.
URL
POST https://<baseURL>/api/atelier/v1/namespace/action/compile
Where <baseURL> is the base URL for your instance.
This call requires the header Content-Type application/json.
URL Parameters
-
The URL parameter 'flags' can be passed (default "cuk") which will be passed to the compiler.
-
The URL parameter 'source' can be passed with a value of 0 if you don't want the source of the compiled source code file to be returned.
JSON Messages
The following is the returned content when compiling Atelier.NewClass1:
{
"status": {
"errors": [],
"summary": ""
},
"console": [
"Compilation started on 01/12/2016 17:44:00 with qualifiers 'cuk'",
"Compiling class Atelier.NewClass1",
"Compiling table Atelier.NewClass1",
"Compiling routine Atelier.NewClass1.1",
"Compilation finished successfully in 0.067s.",
""
],
"result": {
"content": [
{
"name": "Atelier.NewClass1.cls",
"status": "",
"content": [
"Storage Default",
"{",
"<Data name=\"NewClass1DefaultData\">",
"<Value name=\"1\">",
"<Value>%%CLASSNAME</Value>",
"</Value>",
"</Data>",
"<DataLocation>^Atelier.NewClass1D</DataLocation>",
"<DefaultData>NewClass1DefaultData</DefaultData>",
"<IdLocation>^Atelier.NewClass1D</IdLocation>",
"<IndexLocation>^Atelier.NewClass1I</IndexLocation>",
"<StreamLocation>^Atelier.NewClass1S</StreamLocation>",
"<Type>%Storage.Persistent</Type>",
"}",
""
],
"db": "IRISSYS",
"ts": "2016-01-12 17:44:00.053",
"enc": false,
"flags": 1
}
]
}
}
Errors pertaining to a source code file will be in the status property of each source code file object.
If compiling a persistent class causes the storage definition to change, the storage definition is returned as the content of a source code file object. Otherwise the result content will be empty.
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 400 if the resource name is an invalid source code file name.
-
HTTP 404 if the resource is not found.
-
HTTP 423 if the source code file is locked.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
Index
This method returns summary information on the specified source code files. Your application can use this information to create an index to the source code files. It returns an array of index source code file objects.
The list of source code files to be indexed is passed in the body of the http request. The request body is a JSON array of names of source code files. For example, [ "%Api.DocDB.cls", ... ].
URL
POST https://<baseURL>/api/atelier/v1/namespace/action/index
Where <baseURL> is the base URL for your instance.
This call requires the header Content-Type application/json.
JSON Messages
Errors pertaining to a source code file are in the status property of each source code file object. The returned array contains information relating to the structure and documentation of source code files on the server. It will vary by the category to which the source code file belongs. The following is an example for a class (category CLS). (Currently we only support the indexing of classes.):
{
"status": {
"errors": [],
"summary": ""
},
"console": [],
"result": {
"content": [
{
"name": "%Activate.GenericObject.cls",
"db": "IRISLIB",
"ts": "2016-01-04 14:00:04.000",
"gen": false,
"others": [
"%Activate.GenericObject.1.INT"
],
"cat": "CLS",
"content": {
"desc": "This class provides functionality to create an ActiveX object, invoke its methods and Get/Set its properties by name.",
"depl": false,
"depr": false,
"final": false,
"hidden": false,
"super": [
"%Activate.IDispatch"
],
"methods": [
{
"name": "CreateObject",
"desc": "This method is used to create a generic object given only its progid. If the object cannot be found an exception is thrown.
The return value should be tested against $$$NULLOREF in the usual manner to ensure that the object has been successfully created",
"depr": false,
"final": true,
"internal": false,
"private": false,
"scope": "class",
"returntype": "%Library.RegisteredObject",
"args": [
{
"name": "Progid",
"type": "%Library.String"
}
]
},
{
"name": "GetObject",
"desc": "This method is used to create a generic object from a moniker. If the object cannot be found an exception is thrown.
The return value should be tested against $$$NULLOREF in the usual manner to ensure that the object has been successfully created.",
"depr": false,
"final": true,
"internal": false,
"private": false,
"scope": "class",
"returntype": "%Library.RegisteredObject",
"args": [
{
"name": "Moniker",
"type": "%Library.String"
}
]
}
],
"parameters": [],
"properties": []
},
"status": ""
}
]
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 415 if the passed content type is not application/json.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
Query
This method performs an SQL query on an InterSystems IRIS table and returns the results. The request body is a JSON object which specifies the query. It returns an array of objects that match the query conditions. Each returned object contains information relating to one row returned by the query. ee the class reference for Query()Opens in a new tab for supported parameters.
URL
POST https://<baseURL>/api/atelier/v1/namespace/action/query
Where <baseURL> is the base URL for your instance.
The SQL query is specified in the body of the URL request. The query must specify a database in the specified namespace.
This call requires the header Content-Type application/json.
JSON Messages
Return content is an array of objects. Errors will be in the status property of each source code file object:
{
"status": {
"errors": [],
"summary": ""
},
"console": [],
"result": {
"content": [
{
"ID": "%all",
"Description": "The Super-User Role"
},
{
"ID": "%db_%default",
"Description": "R/W access for this resource"
},
{
"ID": "%db_irislocaldata",
"Description": "R/W access for this resource"
},
...
{
"ID": "%sqltunetable",
"Description": "Role for use by tunetable to sample tables irrespective of row level security"
}
]
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 415 if the passed content type is not application/json.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
Search
This method finds files in the InterSystems IRIS database with the specified contents. The Search method is available in version 2 of the API. This method returns the results of the search in a format intended to be displayed to the user.
URL
POST https://<baseURL>/api/atelier/v2/namespace/action/search
Where <baseURL> is the base URL for your instance.
URL Parameters
-
The required URL parameter ?query=expression specifies a regular expression or a text string to search for in the specified files.
-
The required URL parameter ?files=file-list provides a comma-separated list of files or file masks, such as al*.mac, to search for the specified expression.
-
The optional URL parameter ?regex=1 specifies that the query URL parameter contains a regular expression and is the default. ?regexp=0 specifies that the query contains a text string and should not be interpreted as a regular expression.
-
The optional URL parameter ?sys=1 specifies to include system files in the search. The default is ?sys=0, which excludes system files.
-
The optional URL parameter ?gen=1 specifies to include generated files in the search. The default is ?gen=0, which excludes generated files.
-
The optional URL parameter ?max=integer specifies the maximum number of results to return. The default is ?max=200.
JSON Messages
The following search REST call searches all .cls and .mac files for the word “Email” preceded and followed by a space. (In a regular expression, \s is matched by a space character.)
GET localhost:52773/api/atelier/v2/SAMPLES/action/search?query=.*\sEmail\s.*&files=*.cls,*.mac
This call returns the following message. The return message may vary based on the contents of the SAMPLES namespace.
{
"status": {
"errors": [],
"summary": ""
},
"console": [
"",
"Searching for '.*\\sEmail\\s.*' in '*.cls,*.mac'",
"Wasabi.Data.Employee.cls(Email): Property Email ",
"Wasabi.Person.API.Employee.cls(Email): Property Email ",
"ZAUTHENTICATE.mac(175): Properties(\"EmailAddress\") - Email address",
"Found 3 occurrence/s in 3 file/s."
],
"result": [
{
"doc": "Wasabi.Data.Employee.cls",
"matches": [
{
"member": "Email",
"text": "Property Email "
}
]
},
{
"doc": "Wasabi.Person.API.Employee.cls",
"matches": [
{
"member": "Email",
"text": "Property Email "
}
]
},
{
"doc": "ZAUTHENTICATE.mac",
"matches": [
{
"line": "175",
"text": "Properties(\"EmailAddress\") - Email address"
}
]
}
]
}
HTTP Return Codes
-
HTTP 200 if the request is valid.
-
HTTP 400 if there are missing required URL parameters.
GetEnsClassType
This method returns a list of names of the classes meant for use in creating productions. You can specify the type of class to obtain, such as business service classes.
URL
GET https://<baseURL>/api/atelier/v1/namespace/ens/classes/type
Where:
The base URL for your instance.
is an integer and returns classes corresponding to that integer as follows:
Adapters 1
InboundAdapters 2
OutboundAdapters 3
Messages 4
Requests 5
Responses 6
BusinessServices 7
BusinessProcesses 8
BusinessOperations 9
DataTransformation 10
Production 11
BusinessHost 12
Dashboard 13
Rule 14
JSON Messages
The following returned content is an array of class names:
{
status: {
errors: []
summary: ""
}
console: []
result: {
content: [
"Ens.Enterprise.MsgBank.BankTCPAdapter",
"Ens.Enterprise.MsgBank.ClientTCPAdapter",
"Ens.InboundAdapter",
"Ens.OutboundAdapter"
]
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).
GetAdpInputOutputClass
This method returns the input and output type for a specified production adapter.
URL
GET https://<baseURL>/api/atelier/v1/namespace/ens/adapter/name
Where <baseURL> is the base URL for your instance.
JSON Messages
The following is an example of returned content:
{
status: {
errors: []
summary: ""
}
console: []
result: {
content: {
input: "%Stream.Object"
output: "%String"
}
}
}
HTTP Return Codes
-
HTTP 200 if OK.
-
HTTP 404 if the adapter does not exist.
-
HTTP 500 if an unexpected error occurred (details will be in status error array).