Since my last post on the subject, Matt and Jean-Noël have added additional features in REST/HTTP access to OpenDJ data, as well as fixes for issues found in testing.
- The patch operation is now supported.
- The HTTP connection handler now has its own access log.
Patch
OpenDJ now lets you patch JSON resources in addition to replacing them entirely. For example, you can replace an old email address with a new one. The data for the HTTP PATCH request would be an array with a single email value to replace that of the “emailAddress” field.
[
{
"operation": "replace",
"field": "/contactInformation/emailAddress",
"value": "babs@example.com"
}
]
OpenDJ supports four patch “operation” types.
- “add”: ensures the target field of the resource contains the value(s) you provide, creating parent fields as necessary.
- “remove”: ensures the target field does not contain the value(s) you provide. If you do not provide a value, the entire field is removed if it already exists.
- “replace”: like a “remove” followed by an “add”, this removes existing values, replacing them with the values you provide.
- “increment”: increments numeric value(s) when you provide a positive number value. Decrements when you provide a negative number value.
For details on the patch operation types, in particular on how OpenDJ handles single-valued fields versus multi-valued fields, see the draft documentation that’s currently in review.
The “field” value points to the field you aim to change. An important nuance here is that OpenDJ handles arrays as sets. So you cannot have duplicates, and it is not meaningful to reference a value in array by its index. For many operations with identity data, you probably want sets anyway. For example, here’s how you would add Babs Jensen’s entry to a group.
$ curl
--user kvaughan:bribery
--request PATCH
--header "Content-Type: application/json"
--data '[
{
"operation": "add",
"field": "/members",
"value": [
{
"_id": "bjensen"
}
]
}
]'
http://opendj.example.com:8080/groups/Directory%20Administrators
?_prettyPrint=true
{
"_rev" : "00000000b70c881a",
"schemas" : [ "urn:scim:schemas:core:1.0" ],
"_id" : "Directory Administrators",
"displayName" : "Directory Administrators",
"meta" : {
"lastModified" : "2013-05-13T16:40:23Z"
},
"members" : [ {
"_id" : "kvaughan",
"displayName" : "Kirsten Vaughan"
}, {
"_id" : "rdaugherty",
"displayName" : "Robert Daugherty"
}, {
"_id" : "bjensen",
"displayName" : "Barbara Jensen"
}, {
"_id" : "hmiller",
"displayName" : "Harry Miller"
} ]
}
With the patch operation, you can also use resource revision numbers to make sure that you only patch the resource if it still is the version that you expect.
$ curl
--user kvaughan:bribery
"http://opendj.example.com:8080/users/bjensen?_prettyPrint=true&_fields=_rev"
{
"_rev" : "00000000c1b6d4c7"
}
$ curl
--user kvaughan:bribery
--request PATCH
--header "If-Match: 00000000c1b6d4c7"
--header "Content-Type: application/json"
--data '[
{
"operation": "add",
"field": "/contactInformation/emailAddress",
"value": "babs@example.com"
}
]'
http://opendj.example.com:8080/users/bjensen?_prettyPrint=true
{
"_rev" : "00000000f946d377",
"schemas" : [ "urn:scim:schemas:core:1.0" ],
"contactInformation" : {
"telephoneNumber" : "+1 408 555 1862",
"emailAddress" : "babs@example.com"
},
"_id" : "bjensen",
"name" : {
"familyName" : "Jensen",
"givenName" : "Barbara"
},
"userName" : "babs@example.com",
"displayName" : "Barbara Jensen",
"meta" : {
"lastModified" : "2013-05-13T16:56:33Z"
},
"manager" : [ {
"_id" : "trigden",
"displayName" : "Torrey Rigden"
} ]
}
HTTP Access Log
HTTP access to OpenDJ is now logged in logs/http-access, next to the other OpenDJ log files. The HTTP access log format is what you would expect to see in a web server.
localhost kvaughan [13/May/2013:18:54:34 +0200] "GET /users/bjensen/_prettyPrint=true&_fields=_rev HTTP/1.1" 200 "curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5" localhost kvaughan [13/May/2013:18:55:37 +0200] "PATCH /users/bjensen/_prettyPrint=true HTTP/1.1" 200 "curl/7.21.4 (universal-apple-darwin11.0) libcurl/7.21.4 OpenSSL/0.9.8r zlib/1.2.5"
Internal operations performed by the HTTP connection handler are logged to the LDAP access log, logs/access. However, these are hidden by default, because by default the suppress-internal-operations property on the (LDAP) file based access log publisher is set to true. Set it to false if you want to see those internal operations in the LDAP access log. (To see this advanced property when running the dsconfig command interactively, try /path/to/opendj/bin/dsconfig --advanced.)
Although this OpenDJ and the gateway now support each of the CRUDPAQ operations, there are still some improvements on the way, from additional actions (think password modify) to paged results and sorting for searches. I’m still holding off on documenting how to configure authentication, expecting that we will see a simplification of the configuration model.
More to come…
