Diligence is still under development and incomplete, and some this documentation is wrong. For a more comprehensive but experimental version download the Savory Framework, which was the preview release of Diligence.

REST Service

• The default format immediately supports Ext JS's RESTful data stores. Attach any MongoDB collection to an editable grid widget in a web browser! See the Sencha Integration manual for more information.
• Automatic content negotiation with support for JSON and XML formats, as well as a human-readable HTML format perfect for debugging via browsers. The HTML format even allows simple editing of your content. (Note, though, that if you want a full-fledged web frontend for your MongoDB data, you're better off with MongoVision, which is easily installable side-by-side with your Diligence application.)
• Pagination for traversing collections of any size.
• Choose which document fields you want to expose, and extract sub-documents from your main document.
• Apply straightforward "modes," which let you transform MongoDB's extended JSON format into simpler primitives. For example, "{$date: 1234}" would become "1234".

Setup

Manual Setup

app.routes = {
	...
	'/data/users/{id}/': '@users',
	'/data/users/':   '@users.plural'
}
​
app.dispatchers = {
	...
	javascript: '/manual-resources/'
}

document.executeOnce('/diligence/service/rest/')
​
resources = {
	...
	users:     new Diligence.REST.MongoDbResource({name: 'users'}),
	'users.plural': new Diligence.REST.MongoDbResource({name: 'users', plural: true})
} 

Automatic Setup

MongoDB = null
document.execute('/mongo-db/')
​
document.executeOnce('/diligence/service/rest/')
​
app.routes = {
	...
}
​
Sincerity.Objects.merge(app.routes, Diligence.REST.createMongoDbRoutes({prefix: '/data/'}))

Important! The first two lines of code make sure that MongoDB is re-initialized before proceeding, so that we can be sure to avoid using the default MongoDB initialization in other applications. This is good practice when using Diligence in any initialization script.

document.executeOnce('/diligence/service/rest/')
​
resources = {
	...
}
​
Sincerity.Objects.merge(resources, Diligence.REST.createMongoDbResources())

Diligence.REST.createMongoDbResources({collections: ['users','notices','documents']})

Custom Queries

resources = {
	...
	users: new Diligence.REST.MongoDbResource({
		name: 'users',
		query: {_id: {$oid: '{id}'}}
	})
}
​
app.routes = {
	...
	'/data/users/{id}/': {type: 'implicit', id: 'users'}
}

1. If a "/data/users/123/" URI is accessed with a GET operation, the "123" will be extracted from the URI template. The effect will be as if we called:
   

   conversation.locals.put('id', '123')
   

2. All the values in our resource's "query" value are cast using conversation.locals. So, our final query will be:
   

   {_id: {$oid: '123'}}
   

3. The REST Service will use the above query for a "find" operation:

   var data = collection.findOne({_id: {$oid: '123'}})
   

   (Note that the "$oid" in MongoDB's extended JSON becomes an ObjectId in BSON.)

resources = {
	...
	admins: new Diligence.REST.MongoDbResource({
		name: 'users',
		query: {name: '{name}'}, {type: 'admin'}}
	}),
	'admins.plural': new Diligence.REST.MongoDbResource({
		name: 'users',
		query: {type: 'admin'},
		plural: true
	})
}
​
app.routes = {
	...
	'/data/admins/{name}/': {type: 'implicit', id: 'admins'},
	'/data/admins/':    {type: 'implicit', id: 'admins.plural'}
}

new Diligence.REST.MongoDbResource({
	name: 'users',
	query: {name: '{name}'}, {type: '{type}'}},
	values: {type: 'admin'}
})

Custom Extraction

new Diligence.REST.MongoDbResource({
	name: 'users',
	fields: ['name', 'email', 'address']
})

resources = {
	...
	'users.email': new Diligence.REST.MongoDbResource({
		name: 'users',
		fields: 'email',
		extract: 'email'
	}
})
​
app.routes = {
	...
	'/data/users/{id}/email': {type: 'implicit', id: 'users.email'},
}

"myemail@mail.org"

{
	"_id": {
		"$oid": "4e057e94e799a23b0f581d7d"
	},
	"email": "myemail@mail.org"
}

Important! Not all client JSON parsers can deal with JSON data that is not a dict or an array. If you are extracting data that is not a dict or an array, you may need to implement your own special parsing.

resources = {
	...
	'users.groups': new Diligence.REST.MongoDbResource({
		name: 'users',
		fields: 'authorization',
		extract: ['authorization', 'entities']
	}
})
​
app.routes = {
	...
	'/data/users/{id}/groups': {type: 'implicit', id: 'users.groups'},
}

["users", "admins"]

new Diligence.REST.MongoDbResource({
	name: 'users',
	fields: 'authorization',
	extract: function(doc) {
		return doc.authorization.entities.join(',')
	}
})

Custom Modes

new Diligence.REST.MongoDbResource({
	name: 'users',
	modes: {
		flat: function(data) {
			return Sincerity.Objects.flatten(data)
		}
	}
})

Overriding

resources = {
	...
	users: new Diligence.REST.MongoDbResource({name: 'users'})
}
​
resources.users.doDelete = function(conversation) {
	...
	// Call overridden method
	arguments.callee.overridden.call(this, conversation)
}

In-Memory Data

document.executeOnce('/sincerity/jvm/')
​
var users = {
	'4e057e94e799a23b0f581d7d': {
		_id: '4e057e94e799a23b0f581d7d',
		name: 'newton',
		lastSeen: new Date()
	},
	'4e057e94e799a23b0f581d7e': {
		_id: '4e057e94e799a23b0f581d7e',
		name: 'sagan',
		lastSeen: new Date()
	}
}
​
var usersMap = Sincerity.JVM.toMap(users, true)
​
resources = {
	...
	users:     new Diligence.REST.InMemoryResource({name: 'users', documents: usersMap}),
	'users.plural': new Diligence.REST.InMemoryResource({name: 'users', documents: usersMap, plural: true})
}

resources = {
	...
	users:     new Diligence.REST.DistributedResource({name: 'users', documents: users}),
	'users.plural': new Diligence.REST.DistributedResource({name: 'users', documents: users, plural: true})
}

• The "name" field will be used as the name of the Hazelcast map. You can configure this map by name in the Hazelcast configuration, otherwise it will use the Hazelcast defaults for new maps.
• The data from the "documents" field will be copied into the Hazelcast only once and only if the map is already empty. Thus, it should be thought of as your initialization data: the first time a resource is set up for that map, from anywhere in the cluster, this data will be copied in. From then on, for the life of the cluster, "documents" will be ignored. Thus, if you want to re-initialize the map, you will need to either restart your whole cluster, or programmatically set the data. (The Diligence Console would be very useful for that.)
• Note that we are serializing data using JSON into the distributed map. The performance hit should be minimal, but it's important to remember that only your data must be extended-JSON-compatible. (The "InMemoryResource" doesn't have this restriction.)

Usage

Resource Characteristics

• format: You can use this to specify the exact format you want, overriding any HTTP content negotiation. This is useful for testing and debugging, but can also help you in dealing with HTTP clients that can't easily set headers. Accepted values are "json", "xml" and "html". Note that when accessing resources internally, no serialization happens, and "format" is unnecessary.
• human: Setting this to "true" will further help your debugging, as it will return nicely indented, multiline JSON or XML representations.
• mode: "Modes" are simple functions that are applied to all documents in order to transform the final representation. The REST Service comes with a few useful modes, but you can easily create your own, just make sure to hook them to the instance using the "modes" key. The query parameter value will be mapped to a key in this dict. Note that you can provide multiple "mode" values, in which case all mode functions will be called in order. Provided modes:
  • primitive: This converts MongoDB extended values into simpler JSON structures. For example, "{timestamp: {$date: 12345}}" will become "{timestamp: 12345}".
  • string: This converts all JSON values into strings. It's a good way to overcome various number accuracy issues, especially when dealing with PHP clients.
  • stringid: Converts only the "_id" field to a string, in case it's a BSON ObjectId. Some clients, such as Ext JS, cannot deal with ID values that are dicts.

/data/users/4e057e94e799a23b0f581d7d/?format=json&human=true&mode=primitive&mode=string

Singular Resources

• POST: All keys of the payload will be used for a "$set" in a MongoDB "findAndModify" operation, and the modified document will be returned. If you include an "_id" key in the payload it will be removed, because the ID in the URI takes precedence.
• PUT: The payload will become a simple MongoDB "save" operation, which is an upsert, meaning it would either create a new resource or replace the existing one. If you include an "_id" key in the payload it will be removed, because the ID in the URI takes precedence. Note that if you want to create a new resource, it's up to you to make sure the the id is unique, otherwise you will get an HTTP 409 error (conflict). You can generate a unique ID by calling MongoDB.newId(). Example for generating a unique URI using templates:

  '/data/users/{0}/'.cast(MongoDB.newId())
  

Plural Resources

{
	"total": 1092,
	"documents": [
		{"_id": {"$oid": "4e057f2ae799a23b0f581d7f" }, ... }
		...
	]
}

• start: The index from which to start collecting documents. By default it will be 0.
• limit: The maximum number of documents to return.

• POST: This lets you update many documents at once. Your payload should be an array of values that would be sent via the singular resource POST, as described above, however you must also include an "_id" for each value. The response will include all documents after their modification.
• PUT: This is how you add documents to your MongoDB collection. Simply provide an array of values, and they will become MongoDB "insert" operations. The response will include "_id" fields on all your documents, if you did not set them yourself.
• DELETE: This is a MongoDB "remove" operation, not a "drop".

Accessing Your Resources over the Web

Accessing Your Resources with the API

document.executeOnce('/prudence/resources/')
var user = Prudence.Resources.request({
	uri: '/data/users/4e057e94e799a23b0f581d7d/',
	internal: true
})
print(user.name)

Again, we'll emphasize that when accessing the API internally neither HTTP nor serialization are involved. The data is never converted to JSON, instead it's extracted directly from MongoDB's BSON to JavaScript's internal data structure, exactly as if you were using the MongoDB API directly. There's obviously some overhead added by the Prudence platform and the REST Service, but it should be very minimal, especially when compared to the network fetch from MongoDB. In short, performance concerns should not stop you from using the REST Service in this fashion.

var user = Prudence.Resources.request({
	uri: 'http://localhost:8080/myapp/data/users/4e057e94e799a23b0f581d7d/',
	mediaType: 'application/json'
})
print(user.name)

var user = Prudence.Resources.request({
	uri: '/data/users/4e057e94e799a23b0f581d7d/',
	internal: true,
	method: 'post',
	payload: {
		value: {email: 'newemail@mysite.org'}
	}
})

var user = Prudence.Resources.request({
	uri: 'http://localhost:8080/myapp/data/users/4e057e94e799a23b0f581d7d/',
	mediaType: 'application/json'
	method: 'post',
	payload: {
		type: 'json',
		value: {email: 'newemail@mysite.org'}
	}
})

var users = Prudence.Resources.request({
	uri: '/data/users/',
	internal: true,
	query: {
		start: 5,
		limit: 3
	}
})
print(users[0].name)

Accessing Your Resources with cURL

curl "http://localhost:8080/myapp/data/users/4e057e94e799a23b0f581d7d/?human=true"
curl "http://localhost:8080/myapp/data/users/4e057e94e799a23b0f581d7d/?format=xml&human=true"
curl "http://localhost:8080/myapp/data/users/?limit=3&human=true"

curl -d '{"email":"newemail@mysite.org"}' "http://localhost:8080/myapp/data/users/4e057e94e799a23b0f581d7d/?human=true"

curl -d @data.json "http://localhost:8080/myapp/data/users/4e057e94e799a23b0f581d7d/?human=true"

curl -X PUT -d @data.json "http://localhost:8080/myapp/data/users/?human=true"

curl -X DELETE "http://localhost:8080/myapp/data/users/4e057e94e799a23b0f581d7d/"

curl -H "Accept: application/xml" "http://localhost:8080/myapp/data/users/4e057e94e799a23b0f581d7d/?human=true"

Extension

Extended MongoDbResource

Extending IterableResource

The Diligence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.