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\""
   ]
}

Note:

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

GetModifiedDocNames