Read

Examples in this documentation depend on features activated in the ds-evaluation setup profile. For details, refer to Learn about the evaluation setup profile.

The code samples demonstrate how to contact the server over HTTPS using the deployment CA certificate. Before trying the samples, generate the CA certificate in PEM format from the server deployment ID and password:

$ dskeymgr \
 export-ca-cert \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --outputFile ca-cert.pem

Read a resource

Read with HTTP GET:

Curl
JavaScript
Python
Ruby

$ curl \
 --get \
 --cacert ca-cert.pem \
 --user dc=com/dc=example/ou=People/uid=kvaughan:bribery \
 --header 'Content-Type: application/json' \
 --data '_prettyPrint=true' \
'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=bjensen'
{
  "_id" : "dc=com/dc=example/ou=People/uid=bjensen",
  "_rev" : "<revision>",
  "objectClass" : [ "person", "cos", "oauth2TokenObject", "inetOrgPerson", "organizationalPerson", "posixAccount", "top" ],
  "classOfService" : "bronze",
  "cn" : [ "Barbara Jensen", "Babs Jensen" ],
  "departmentNumber" : [ "3001" ],
  "description" : [ "Original description" ],
  "diskQuota" : [ "10 GB" ],
  "facsimileTelephoneNumber" : [ "+1 408 555 1992" ],
  "gidNumber" : 1000,
  "givenName" : [ "Barbara" ],
  "homeDirectory" : "/home/bjensen",
  "l" : [ "San Francisco" ],
  "mail" : [ "bjensen@example.com" ],
  "mailQuota" : [ "1 GB" ],
  "manager" : [ "dc=com/dc=example/ou=People/uid=trigden" ],
  "oauth2Token" : [ {
    "access_token" : "123",
    "expires_in" : 59,
    "token_type" : "Bearer",
    "refresh_token" : "456"
  } ],
  "ou" : [ "Product Development", "People" ],
  "preferredLanguage" : "en, ko;q=0.8",
  "roomNumber" : [ "0209" ],
  "sn" : [ "Jensen" ],
  "street" : [ "201 Mission Street Suite 2900" ],
  "telephoneNumber" : [ "+1 408 555 1862" ],
  "uid" : [ "bjensen" ],
  "uidNumber" : 1076,
  "userPassword" : [ "<hashed-password>" ]
}

(async () => {
    const { authenticate, doRequest, getOptions } = require('./utils')
    const options = getOptions({
        path: '/hdap/dc=com/dc=example/ou=People/uid=bjensen'
    })
    const jwt = await authenticate(options)
    options.headers['Authorization'] = 'Bearer ' + jwt
    const response = await doRequest('HDAP: read with GET', options)
    console.log(response)
})().catch(error => { console.error(error) })

Source files for this sample: read.js, utils.js

#!/usr/bin/env python3

import requests
import utils

jwt = utils.authenticate('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
response = requests.get(
    f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example/ou=People/uid=bjensen',
    headers=headers,
    verify=utils.ca_pem)
print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))

Source files for this sample: utils.py, read.py

require_relative 'utils.rb'
require 'faraday'

utils = Utils.new('dc=com/dc=example/ou=People/uid=bjensen', 'hifalutin')
options = { ca_file: utils.ca_pem }
jwt = utils.authenticate
hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", ssl: options) do |f|
    f.headers['Content-Type'] = 'application/json'
    f.request :authorization, 'Bearer', jwt
end
response = hdap.get('dc=com/dc=example/ou=People/uid=bjensen')

puts "Status code: #{response.status}\nJSON: #{response.body}"

Source files for this sample: utils.rb, read.rb

HDAP Ruby examples require Ruby 3.2 and the faraday and json gems.

Read specific fields

HDAP can return only specified fields in the resource. Use the _fields parameter:

Curl
JavaScript
Python
Ruby

$ curl \
 --get \
 --cacert ca-cert.pem \
 --user dc=com/dc=example/ou=People/uid=kvaughan:bribery \
 --header 'Content-Type: application/json' \
 --data '_fields=cn,mail' \
 --data '_prettyPrint=true' \
'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=bjensen'
{
  "_id" : "dc=com/dc=example/ou=People/uid=bjensen",
  "_rev" : "<revision>",
  "mail" : [ "bjensen@example.com" ],
  "cn" : [ "Barbara Jensen", "Babs Jensen" ]
}

(async () => {
    const { authenticate, doRequest, getOptions } = require('./utils')
    const options = getOptions({
        path: '/hdap/dc=com/dc=example/ou=People/uid=bjensen?_fields=cn,mail'
    })
    const jwt = await authenticate(options)
    options.headers['Authorization'] = 'Bearer ' + jwt
    const response = await doRequest('HDAP: read specific fields', options)
    console.log(response)
})().catch(error => { console.error(error) })

Source files for this sample: read-fields.js, utils.js

#!/usr/bin/env python3

import requests
import utils

params = { '_fields': 'cn,mail' }
jwt = utils.authenticate('dc=com/dc=example/ou=People/uid=kvaughan', 'bribery')
headers = { 'Content-Type': 'application/json', 'Authorization': f'Bearer {jwt}' }
response = requests.get(
    f'https://{utils.host}:{utils.port}/hdap/dc=com/dc=example/ou=People/uid=bjensen',
    headers=headers,
    params=params,
    verify=utils.ca_pem)
print('Status code: %d\nJSON: %s' % (response.status_code, response.json()))

Source files for this sample: utils.py, read-fields.py

require_relative 'utils.rb'
require 'faraday'

utils = Utils.new('dc=com/dc=example/ou=People/uid=bjensen', 'hifalutin')
options = { ca_file: utils.ca_pem }
jwt = utils.authenticate
fields = { '_fields': 'cn,mail' }
hdap = Faraday.new(url: "https://#{utils.host}:#{utils.port}/hdap/", params: fields, ssl: options) do |f|
    f.headers['Content-Type'] = 'application/json'
    f.request :authorization, 'Bearer', jwt
end
response = hdap.get('dc=com/dc=example/ou=People/uid=bjensen')

puts "Status code: #{response.status}\nJSON: #{response.body}"

Source files for this sample: utils.rb, read-fields.rb

HDAP Ruby examples require Ruby 3.2 and the faraday and json gems.

DS 7.5.0

Read

Read a resource

Read specific fields