Skip to main content
Previous section

REST Client Methods

InterSystems IRIS® data platform DocDB REST Client API supplies methods that enable you to work with DocDB from REST. The REST API differs from other DocDB APIs because REST acts on resources while the other APIs act on objects. This resource orientation is fundamental to the nature of REST.

The curl examples in this chapter specify port number 57774. This is only an example. You should use the port number appropriate for your InterSystems IRIS instance.

In curl the GET command is the default; therefore, a curl command that omits -X GET defaults to -X GET.

For DocDB the only valid Content-Type is application/json. If an unexpected Content-Type is requested then an HTTP Response Code = 406 is issued.

For further details on the REST API refer to the %Api.DocDB.v1 in the InterSystems Class Reference. For further details on REST, refer to Creating REST Services.

Managing Databases

  • GetAllDatabases: Returns a JSON array which contains the names of all of the databases in the namespace.

    curl -i -X GET -H "Content-Type: application/json" http://localhost:57774/api/docdb/v1/namespaceName
    Copy code to clipboard
  • DropAllDatabases: Deletes all of the databases in the namespace for which the current user has Write privileges.

    curl -i -X DELETE -H "Content-Type: application/json" http://localhost:57774/api/docdb/v1/namespaceName
    Copy code to clipboard
  • CreateDatabase: Creates a database in the namespace.

    curl -i -X POST -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/db/databaseName ?type= documentType& resource= databaseResource
    Copy code to clipboard
  • GetDatabase: Returns the database definition of a database in the namespace.

    curl -i -X GET -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/db/databaseName
    Copy code to clipboard
  • DropDatabase: Drops a database from the namespace.

    curl -i -X DELETE -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/db/databaseName
    Copy code to clipboard

Managing Properties

  • CreateProperty: Creates a new property or replaces an existing property in the specified database. The property is defined by URL parameters and not Content. All parameters are optional.

    curl -i -X POST -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/prop/databaseName/ 
    propertyName?type= propertyType& path= propertyPath& unique=propertyUnique
    Copy code to clipboard

    The following example creates the City property in the Wx database:

    http://localhost:57774/api/docdb/v1/mysamples/prop/wx/city?type=%String&path=query.results.channel.location.city&0
    Copy code to clipboard
  • GetProperty: Returns a property definition from the specified database.

    curl -i -X GET -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/prop/databaseName/propertyName
    Copy code to clipboard

    The returned property definition is a JSON structure such as the following:

    {"content":{"Name":"city","Type":"%Library.String"}}
    Copy code to clipboard
  • DropProperty: Deletes a property definition from the specified database.

    curl -i -X DELETE -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/prop/databaseName/propertyName
    Copy code to clipboard

The following is a JSON property definition:

{"content":{"Name":"mydocdb","Class":"DB.MyDocDb","properties":[Array[5]
   0: {"Name":%%OTD,"Type":"%RawString"},
   1: {"Name":%Concurrency,"Type":"%RawString"},
   2: {"Name":%Doc,"Type":"%Library.DynamicAbstractObject"},
   3: {"Name":%DocumentId,"Type":"%Library.Integer"},
   4: {"Name":%LastModified,"Type":"%Library.UTC"}
   ]}}
Copy code to clipboard

Inserting and Updating Documents

  • SaveDocument: Insert a new document into the specified database.

    curl -i -X POST -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/doc/databaseName/
    Copy code to clipboard

    Note there is a slash at the end of this URI.

    To insert one or more documents, perform a POST. The body of the request is either a JSON document object or a JSON array of document objects. Note that the document objects may be in the unwrapped form with just content. This unwrapped form always results in an insert with a new %DocumentId. Specifying a wrapped document object whose %DocumentId is not present in the database results in an insert with that %DocumentId. Otherwise, the %DocumentId property is ignored and an insert with a new %DocumentId takes place. If the request is successful, a single JSON document header object or an array of JSON document header objects is returned. If the request fails, the JSON header object is replaced by an error object.

  • SaveDocument: Replace an existing document in the specified database.

    curl -i -X PUT -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/doc/databaseName/id
    Copy code to clipboard

    To insert a single JSON document object at a specific id location. If the specified %DocumentId already exists, the system replaces the existing document with the new document.

  • SaveDocumentByKey: Replace an existing document in the specified database.

    curl -i -X PUT -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/doc/databaseName/keyPropertyName/keyValue
    Copy code to clipboard

Deleting Documents

  • DeleteDocument: Delete a document from the specified database.

    curl -i -X DELETE -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/doc/databaseName/id
    Copy code to clipboard

    Deletes the document specified by %DocumentId. If the request is successful, the specified document is deleted, the document wrapper metadata {"%DocumentId":<IDnum>,"%LastModified":<timestamp>} is returned, and a 200 (OK) status.

  • DeleteDocumentByKey: Delete a document from the specified database.

    curl -i -X DELETE -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/doc/databaseName/keyPropertyName/keyValue
    Copy code to clipboard

Retrieving a Document

  • GetDocument: Return the specified document from the database.

    curl -i -X GET -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/doc/databaseName/id? wrapped=true|false
    Copy code to clipboard
  • GetDocumentByKey: Return a document by a property defined as a unique key from the database.

    curl -i -X POST -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/doc/databaseName/keyPropertyName/keyValue
    Copy code to clipboard

    FindDocuments: Return all documents from the database that match the query specification.

    curl -i -X POST -H "Content-Type: application/json" 
    http://localhost:57774/api/docdb/v1/namespaceName/find/databaseName? wrapped=true|false
    Copy code to clipboard

The following curl script example supplies full user credentials and header information. It returns all of the documents in the Continents document database in the MySamples namespace:

curl --user _SYSTEM:SYS -w "\n\n%{http_code}\n" -X POST 
-H "Accept: application/json" -H "Content-Type: application/json" 
http://localhost:57774/api/docdb/v1/mysamples/find/continents
Copy code to clipboard

It returns JSON data from the Document database such as the following:

{"content":{"sqlcode":100,"message":null,"content":[
  {"%Doc":"{\"code\":\"NA\",\"name\":\"North America\"}","%DocumentId":"1","%LastModified":"2018-02-15 21:33:03.64"},
  {"%Doc":"{\"code\":\"SA\",\"name\":\"South America\"}","%DocumentId":"2","%LastModified":"2018-02-15 21:33:03.64"},
  {"%Doc":"{\"code\":\"AF\",\"name\":\"Africa\"}","%DocumentId":"3","%LastModified":"2018-02-15 21:33:03.64"},
  {"%Doc":"{\"code\":\"AS\",\"name\":\"Asia\"}","%DocumentId":"4","%LastModified":"2018-02-15 21:33:03.64"},
  {"%Doc":"{\"code\":\"EU\",\"name\":\"Europe\"}","%DocumentId":"5","%LastModified":"2018-02-15 21:33:03.64"},
  {"%Doc":"{\"code\":\"OC\",\"name\":\"Oceana\"}","%DocumentId":"6","%LastModified":"2018-02-15 21:33:03.64"},
  {"%Doc":"{\"code\":\"AN\",\"name\":\"Antarctica\"}","%DocumentId":"7","%LastModified":"2018-02-15 21:33:03.64"}]}}
Copy code to clipboard

Restriction: The following curl script example restricts the documents returned from the Continents document database by specifying a restriction object. This restriction limits the documents returned to those whose name begins with the letter A:

curl --user _SYSTEM:SYS -w "\n\n%{http_code}\n" -X POST 
-H "Accept: application/json" -H "Content-Type: application/json" 
http://localhost:57774/api/docdb/v1/mysamples/find/continents -d
'{"restriction":["Name","A","%STARTSWITH"]}'
Copy code to clipboard

It returns the following JSON documents from the Document database:

{"content":{"sqlcode":100,"message":null,"content":[
  {"%Doc":"{\"code\":\"AF\",\"name\":\"Africa\"}","%DocumentId":"3","%LastModified":"2018-02-15 21:33:03.64"},
  {"%Doc":"{\"code\":\"AS\",\"name\":\"Asia\"}","%DocumentId":"4","%LastModified":"2018-02-15 21:33:03.64"},
  {"%Doc":"{\"code\":\"AN\",\"name\":\"Antarctica\"}","%DocumentId":"7","%LastModified":"2018-02-15 21:33:03.64"}]}}
Copy code to clipboard

Projection: The following curl script example projects which JSON properties to return from each document in the Continents document database. It uses the same restriction as the previous example:

curl --user _SYSTEM:SYS -w "\n\n%{http_code}\n" -X POST 
-H "Accept: application/json" -H "Content-Type: application/json" 
http://localhost:57774/api/docdb/v1/mysamples/find/continents -d
'{"restriction":["Name","A","%STARTSWITH"],"projection":["%DocumentId","name"]}'
Copy code to clipboard

It returns JSON data from the Document database such as the following:

{"content":{"sqlcode":100,"message":null,"content":[
  {"%Doc":"{"%DocumentId":"3","name":"Africa"}},
  {"%Doc":"{"%DocumentId":"4","name":"Asia"}},
  {"%Doc":"{"%DocumentId":"7","name":"Antarctica"}}]}}
Copy code to clipboard