Document Store API v1

Objects

Storing data in Docmingo is built around a JSON encoding of the object’s data. The data is schemaless and you don’t need to specify ahead of time what keys exist on each object. Simply set whatever key-value pairs you want and store it in Docmingo.

For example, let’s say you’re tracking user info for some application. A sample object could contain:

{
  "userId": "8e80b36c-ab67-11e6-82b1-fa163e7504ec",
  "address1": "some address",
  "address2": "",
  "city": "Philadelphia",
  "state": "PA"
}

Note: keys must be alphanumeric strings and values can be anything that can be JSON-encoded.

Each object has a class name that you can use to distinguish different sorts of data. In our example above class name could be UserInfo. It is recommended that you NameYourClassesLikeThis and nameYourKeysLikeThis.

It is important to note that once you save your new object some fields are added to it automatically. These fields are createdAt, updatedAt, and objectId. These field names are reserved, so you cannot set them yourself. If you attempt to set them anyway, they will be ignored and overwritten by Docmingo.

Our sample UserInfo object defined above would return the following fields after it was saved:

{
  "userId": "8e80b36c-ab67-11e6-82b1-fa163e7504ec",
  "address1": "some address",
  "address2": "",
  "city": "Philadelphia",
  "state": "PA",
  "updatedAt": 1481555045655,
  "createdAt": 1481555045655,
  "objectId": "584ebc65d0bf61dd16638c7f"
}

createdAt and updatedAt are Unix time in seconds since Jan 01 1970. (UTC). objectId is a string unique to this class that identifies the object.

Creating Objects

POST /v1/classes/:classname (client) POST /v1/classes/:classname/userid/:userid (server-to-server)

Description

Create object with :classname as class name and some user defined key-value payload.

Request client

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
-d '{"firstName": "John", "lastName": "Smith"}'
https://ds.iris.comcast.net/v1/classes/UserInfo

Request app server

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
-d '{"firstName": "John", "lastName": "Smith"}'
https://ds.iris.comcast.net/v1/classes/UserInfo/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Request server

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
-d '{"firstName": "John", "lastName": "Smith"}'
https://ds.iris.comcast.net/v1/classes/UserInfo/domain/app-1.comcast.com/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Sample output

{
  "firstName": "John",
  "lastName": "Smith",
  "objectId": "584edad2c636a3df1e4a0631",
  "createdAt": 1481562834519,
  "updatedAt": 1481562834519
}

Create or Update Object

PUT /v1/classes/:classname (client) PUT /v1/classes/:classname/userid/:userid (server-to-server)

Description

This API allows you to specify query to use for finding the object. If the object is found it is updated with the content specified in object field. If the object is not found a new object is created with the content specified in object field.

Request client

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
-d '{
  "query": {
        "userId": "12345"
    },
    "object": {
        "userId": "12345",
        "mailboxName": "Mailbox 1",
        "counter": 0
    }
}'
https://ds.iris.comcast.net/v1/classes/UserInfo

Request app server

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
-d '{
  "query": {
        "userId": "12345"
    },
    "object": {
        "userId": "12345",
        "mailboxName": "Mailbox 1",
        "counter": 0
    }
}'
https://ds.iris.comcast.net/v1/classes/UserInfo/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Request server

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
-d '{
  "query": {
        "userId": "12345"
    },
    "object": {
        "userId": "12345",
        "mailboxName": "Mailbox 1",
        "counter": 0
    }
}'
https://ds.iris.comcast.net/v1/classes/UserInfo/domain/app-1.comcast.com/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Sample output

{
  "updatedAt": 1481821432268,
  "createdAt": 1481821347427,
  "objectId": "5852cca36ee417045500a73a",
  "mailboxName": "Mailbox 1",
  "userId": "12345",
  "counter": 0
}

Retrieving Objects

GET /v1/classes/:classname (client) GET /v1/classes/:classname/userid/:userid (server-to-server)

Description

You can retrieve objects for the specified class name, domain and user(s). Note: With this API client has only ability to get objects for the user it is associated with. However, both application server and core servers can either pass specific userid or wildcard * to view objects for all users in the app domain.

Requests client

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
https://ds.iris.comcast.net/v1/classes/UserInfo

Request app server

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec
or with wildcard

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/userid/*

Request server

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/domain/app-1.comcast.com/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec
or with wildcard

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/domain/app-1.comcast.com/userid/*

Sample output

[
  {
    "updatedAt": 1481205574246,
    "createdAt": 1481205574246,
    "objectId": "58496746a600f5c59360f29b",
    "lastName": "Last Name 1",
    "firstName": "First Name 1"
  },
  {
    "updatedAt": 1481207494995,
    "createdAt": 1481207494995,
    "objectId": "58496ec61b8064c61fc15978",
    "lastName": "Last Name 4",
    "firstName": "First Name 4"
  },
  {
    "updatedAt": 1481210267291,
    "createdAt": 1481207580160,
    "objectId": "58496f1c1b8064c61fc15979",
    "lastName": "NEW Last Name 5",
    "firstName": "NEW First Name 5"
  },
  {
    "updatedAt": 1481224000911,
    "createdAt": 1481224000911,
    "objectId": "5849af40f0d20cc8eb56f764",
    "status": "A"
  },
  {
    "updatedAt": 1481224128439,
    "createdAt": 1481224128439,
    "objectId": "5849afc017750ac90e0a4efe",
    "status": "A"
  },
  {
    "updatedAt": 1481383557088,
    "createdAt": 1481383557088,
    "objectId": "584c1e85d9e3d7d259b0424e",
    "lastName": "User 2 Last Name 1",
    "firstName": "User 2 First Name 1"
  },
  {
    "updatedAt": 1481553640640,
    "createdAt": 1481553640640,
    "objectId": "584eb6e8f5ac9ddce958343a",
    "lastName": "Last Name 6",
    "firstName": "First Name 6"
  },
  {
    "updatedAt": 1481555045655,
    "createdAt": 1481555045655,
    "objectId": "584ebc65d0bf61dd16638c7f",
    "lastName": "AppServer Last Name 1",
    "firstName": "AppServer First Name 1"
  },
  {
    "updatedAt": 1481555617870,
    "createdAt": 1481555617870,
    "objectId": "584ebea1d0bf61dd16638c80",
    "lastName": "Server Last Name 1",
    "firstName": "Server First Name 1"
  },
  {
    "updatedAt": 1481562753311,
    "createdAt": 1481562753311,
    "objectId": "584eda81c636a3df1e4a0630",
    "lastName": "Last Name 8",
    "firstName": "First Name 8"
  },
  {
    "updatedAt": 1481562834519,
    "createdAt": 1481562834519,
    "objectId": "584edad2c636a3df1e4a0631",
    "lastName": "Server Last Name 2",
    "firstName": "Server First Name 2"
  }
]

Retrieving Objects with Pagination

GET /v1/classes/:classname/start/:start/count/:count (client) GET /v1/classes/:classname/userid/:userid/start/:start/count/:count (server-to-server)

Description

You can retrieve objects for the specified class name, domain and user(s). Note: With this API client has only ability to get objects for the user it is associated with. However, both application server and core servers can either pass specific userid or wildcard * to view objects for all users in the app domain.

start parameter specifies starting element number and count parameter specifies number of entries to return. Note, that API may return less than what was requested in count parameter if there are not that many elements.

This API returns object with result key containing the list of the objects. It also returns start that is equal to requested start parameter. count that is either the requested count or the number of elements left in query. There is also max key that shows total number of elements in query.

Requests client

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
http://ds.iris.comcast.net/v1/classes/UserInfo/start/2/count/2

Request app server

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec/start/2/count/2
or with wildcard

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/userid/*/start/2/count/2

Request server

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/domain/robs-test-app-1.comcast.com/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec/start/2/count/2
or with wildcard

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/domain/robs-test-app-1.comcast.com/userid/*/start/2/count/2

Sample output

{
  "result": [
    {
      "updatedAt": 1481210267291,
      "createdAt": 1481207580160,
      "objectId": "58496f1c1b8064c61fc15979",
      "lastName": "NEW Last Name 5",
      "firstName": "NEW First Name 5"
    },
    {
      "updatedAt": 1481224000911,
      "createdAt": 1481224000911,
      "objectId": "5849af40f0d20cc8eb56f764",
      "status": "A"
    }
  ],
  "start": 2,
  "count": 2,
  "max": 11
}

Retrieving Specific Object

GET /v1/classes/:classname/:objectid (client) GET /v1/classes/:classname/:objectid/userid/:userid (server-to-server)

Description

This API returns specific object in class by objectId.

Requests client

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80

Request app server

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Request server

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80/domain/app-1.comcast.com/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Sample output

{ "firstName": "First Name 1", "lastName": "Last Name 1", "objectId": "584ebea1d0bf61dd16638c80", "createdAt": 1481555617870, "updatedAt": 1481555617870 }

Get Object Count For Class

GET /v1/classes/:classname/count (client) GET /v1/classes/:classname/count/userid/:userid (server-to-server)

Description

This API returns count of objects in the class.

Requests client

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/count

Request app server

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/count/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Request server

curl -X GET -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/count/domain/app-1.comcast.com/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Sample output

{ count: 9 }

Update Operators

This section describes update operators.

$inc

$inc is an atomic operator that takes positive and negative values. If the specified field does not exist, it will create the field and set it to the specified value. If $inc operator is used on a field with a null value it will generate an error.

Example:

{ "$inc": { "counter": 2 } }

$mul

$mul is an atomix operator that multiplies value in the field by specified number.

Example:

{ $"mul": { "price": 2 } }

$min

The $min updates the value of the field to a specified value if the specified value is less than the current value of the field. If the field does not exists, the $min operator sets the field to the specified value.

Example:

{ "$min": { "score": 100 } }

$max

The $max operator updates the value of the field to a specified value if the specified value is greater than the current value of the field. If the field does not exists, the $max operator sets the field to the specified value.

Example:

{ $max: { core: 900 } }

$pop

This operator removes the first or last element of an array. Use a value of -1 to remove the first element of an array and 1 to remove the last element in an array. If the field is not an array the operation will fail.

Example:

{ "$pop": { "scores": -1 } }

$pullAll

The $pullAll operator removes all instances of the specified values from an existing array.

Example:

{ "$pullAll": { "scores": [ 8, 5 ] } }

$pull

Removes elements from an array that match the specified condition.

Example:

{ "$pull": { "fruits": { "$in": [ "apples", "oranges" ] } } }
{ "$pull": { "vegetables": "carrots" } }

$push

The $push operator appends a specified value to an array.

Supports following modifiers:

$each - Appends multiple values to the array field. $slice - Limits the number of array elements. $sort - Orders elements of the array. $position - Specifies the location in the array at which to insert the new elements. Examples:

{"$push": {"scores": {"$each": [11, 12, 13], "$position": 1}}}

{ "$push": { "scores": 89 } }

"$push": {
  "quizzes": {
    "$each": [ { "wk": 5, "score": 8 }, { "wk": 6, "score": 7 }, { "wk": 7, "score": 6 } ],
    "$sort": { "score": -1 },
    "$slice": 3
  }
}

Update Object

PUT /v1/classes/:classname/:objectid (client) PUT /v1/classes/:classname/:objectid/userid/:userid (server-to-server)

Description

To update the existing object specify new values in the json payload. Note that updatedAt field will be automatically updated with the time of transaction.

Requests client

curl -X PUT -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
-d '{"firstName": "New First Name 1", "lastName": "New Last Name 1"}'
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80

Request app server

curl -X PUT -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
-d '{"firstName": "New First Name 1", "lastName": "New Last Name 1"}'
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Request server

curl -X PUT -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
-d '{"firstName": "New First Name 1", "lastName": "New Last Name 1"}'
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80/domain/app-1.comcast.com/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Sample output

{
  "firstName": "New First Name 1",
  "lastName": "New Last Name 1",
  "objectId": "584edad2c636a3df1e4a0631",
  "createdAt": 1481562834519,
  "updatedAt": 1481562834620
}

Delete Object

DELETE /v1/classes/:classname/:objectid (client) DELETE /v1/classes/:classname/:objectid/userid/:userid (server-to-server)

Description

This API deletes object specified by objectId and returns the deleted object.

Requests client

curl -X DELETE -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80

Request app server

curl -X DELETE -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Request server

curl -X DELETE -H "Content-Type: application/json"
-H "Authorization: Bearer <server-to-server token>"
https://ds.iris.comcast.net/v1/classes/UserInfo/584ebea1d0bf61dd16638c80/domain/app-1.comcast.com/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Sample output

{
  "firstName": "New First Name 1",
  "lastName": "New Last Name 1",
  "objectId": "584edad2c636a3df1e4a0631",
  "createdAt": 1481562834519,
  "updatedAt": 1481562834620
}

Queries

Docmingo provides query API endpoint. This API allows to retrieve objects based on specified query selectors. Following are supported query selectors:

Query Selectors

Comparison

  • $eq Matches values that are equal to a specified value.
  • $gt Matches values that are greater than a specified value.
  • $gte Matches values that are greater than or equal to a specified value.
  • $lt Matches values that are less than a specified value.
  • $lte Matches values that are less than or equal to a specified value.
  • $ne Matches all values that are not equal to a specified value.
  • $in Matches any of the values specified in an array.
  • $nin Matches none of the values specified in an array.

Logical

  • $or Joins query clauses with a logical OR returns all documents that match the conditions of either clause.
  • $and Joins query clauses with a logical AND returns all documents that match the conditions of both clauses.
  • $not Inverts the effect of a query expression and returns documents that do not match the query expression.
  • $nor Joins query clauses with a logical NOR returns all documents that fail to match both clauses.

Element

  • $exists Matches documents that have the specified field.
  • $type Selects documents if a field is of the specified type.

Evaluation

  • $regex Selects documents where values match a specified regular expression.

Array

  • $all Matches arrays that contain all elements specified in the query.
  • $elemMatch Selects documents if element in the array field matches all the specified $elemMatch conditions.
  • $size Selects documents if the array field is a specified size.

Bitwise

  • $bitsAllSet Matches numeric or binary values in which a set of bit positions all have a value of 1.
  • $bitsAnySet Matches numeric or binary values in which any bit from a set of bit positions has a value of 1.
  • $bitsAllClear Matches numeric or binary values in which a set of bit positions all have a value of 0.
  • $bitsAnyClear Matches numeric or binary values in which any bit from a set of bit positions has a value of 0.

Select All Documents in a Collection

An empty query filter object {} selects all objects in the collection.

Specify Equality Condition

A query filter object can specify equality condition with : expressions to select all objects that contain the with the specified :

{ : , ... }

Example, retrieve all objects where the status field has the value "A":

{ status: "A" }

Specify Conditions Using Query Operators

A query filter object can use the query operators to specify conditions in the following form:

{ : { :  }, ... }

Example, retrieve all objects where status equals either "A" or "B":

{ status: { $in: [ "A", "B" ] } }

Specify AND Conditions

A compound query can specify conditions for more than one field in the class. Multiple queries put together imply logical AND.

Example, retrieves all objects with status equals "A" and age is less than ($lt) 30:

{ status: "A", age: { $lt: 30 } }

Specify OR Conditions

Use $or to specify logical OR.

Example, retrieves all objects where the status equals "A" or age is less than ($lt) 30:

{
 $or: [ { status: "A" }, { age: { $lt: 30 } } ]
}

Specify AND as well as OR Conditions

You can mix clauses to achieve whatever matching conditions you desire. With additional clauses, you can specify precise conditions for matching documents.

Example:

{
 status: "A",
 $or: [ { age: { $lt: 30 } }, { type: 1 } ]
}

Query on Embedded Documents

When the field holds an embedded object, a query can either specify an exact match on the embedded object or specify a match by individual fields in the embedded object using the dot notation.

{ favorites: { artist: "Picasso", food: "pizza" } }

or

{ "favorites.artist": "Picasso" }

Exact Match on an Array

This example queries for all objects where the field badges is an array that holds exactly two elements, "blue", and "black", in this order:

{ badges: [ "blue", "black" ] }

Match an Array Element

This example queries for all objects where badges is an array that contains "black" as one of its elements:

{ badges: "black" }

Sort, limit, select

In addition to query you can specify sort, limit and select commands.

Sort will sort query result based on the criteria passed in format { key: value } where value is either -1 or 1 for descending or ascending.

Limit will return only the specified number of objects from query.

Select allows you to specify which fields to return. Format is { "fieldname1": 1, "fieldname2": 1, ... }

Skip, limit, getCount

With skip, limit, and getCount you can paginate the query output.

Here is the example of query that does pagination. In this example, it starts with the third entry and gets three entries at the time as well as total count of entries in the query.

  {
    query: {
      id: UserId
    },
    skip: 2,
    limit: 3,
    getCount: 1
  }

getCountOnly

getCountOnly allows to retrieve just count for the specific query.

  {
    query: {
      id: UserId
    },
    getCountOnly: 1
  }

Sample output

  { count: 9 }

Query API

POST /v1/query/:classname (client) POST /v1/query/:classname/userid/:userid (server-to-server)

Example (client):

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Bearer <client token>"
-d '{
    "query": {
        "$or": [{"status": "A"}, {"lastName": "Last Name 1"}]
    },
    "sort": { "objectId": -1 },
    "select": { "updatedAt": 1, "objectId": 1 }
}'
https://ds.iris.comcast.net/v1/query/UserInfo

Example (server-to-server):

curl -X POST -H "Content-Type: application/json"
-H "Authorization: Bearer <appserver-to-server token>"
-d '{
    "query": {
        "$or": [{"status": "A"}, {"lastName": "Last Name 1"}]
    },
    "sort": { "objectId": -1 },
    "select": { "updatedAt": 1, "objectId": 1 }
}'
https://ds.iris.comcast.net/v1/query/UserInfo/userid/8e80b36c-ab67-11e6-82b1-fa163e7504ec

Sample results:

[
  {
    "updatedAt": 1481224128439,
    "objectId": "5849afc017750ac90e0a4efe"
  },
  {
    "updatedAt": 1481224000911,
    "objectId": "5849af40f0d20cc8eb56f764"
  },
  {
    "updatedAt": 1481205574246,
    "objectId": "58496746a600f5c59360f29b"
  }
]

Version

GET /v1/version

Description

Returns Iris Document Server version number. Note: this API end point does not require Authorization header.

Example

curl -X GET https://ds.iris.comcast.net/v1/version
← Document StoreAPI Reference →