Skip to main content

Using Document Database with REST

The InterSystems IRIS® data platform Document Database REST client supplies methods that enable you to work with Document Databases from REST (see Creating REST Services for detailed information on InterSystems REST support). The REST API differs from Document Database clients in other programming languages because REST acts on resources while the other clients 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 Document Database the only valid Content-Type is application/json. If an unexpected Content-Type is requested then an HTTP Response Code = 406 is issued.

To use the REST API, you must enable the %Service_DocDB service. To do so, navigate to System Administration > Security > Services, select %Service_DocDB, and select the %Service_DocDB checkbox.

For further details on the REST API refer to the %Api.DocDB.v1Opens in a new tab in the InterSystems Class Reference.

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
    
  • 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
    
  • 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
    
  • 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
    
  • 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
    

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
    

    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
    
  • 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
    

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

    {"content":{"Name":"city","Type":"%Library.String"}}
    
  • 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
    

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

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/
    

    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
    

    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
    

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
    

    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
    

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
    
  • 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
    

    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
    

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

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

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

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

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

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"}}]}}
FeedbackOpens in a new tab