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