---
title: Read
description: Examples in this documentation depend on features activated in the ds-evaluation setup profile.
component: pingds
version: 8.1
page_id: pingds:rest-guide:read-rest
canonical_url: https://docs.pingidentity.com/pingds/8.1/rest-guide/read-rest.html
revdate: 2025-10-22T14:42:39Z
keywords: ["REST API"]
section_ids:
  read-rest-resource: Read a resource
  read-rest-fields: Read specific fields
---

# Read

|   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Examples in this documentation depend on features activated in [the `ds-evaluation` setup profile](../install-guide/setup-ds.html#about-ds-evaluation).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:```console
$ dskeymgr \
 export-ca-cert \
 --deploymentId $DEPLOYMENT_ID \
 --deploymentIdPassword password \
 --outputFile ca-cert.pem
``` |

## Read a resource

Read with HTTP GET:

* Curl

* JavaScript

* Python

* Ruby

```console
$ 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'
```

> **Collapse: Show output**
>
> ```
> {
>   "_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>" ]
> }
> ```

```javascript
(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](../_attachments/hdap/js/read.js), [utils.js](../_attachments/hdap/js/utils.js)

```python
#!/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](../_attachments/hdap/py/utils.py), [read.py](../_attachments/hdap/py/read.py)

```ruby
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](../_attachments/hdap/rb/utils.rb), [read.rb](../_attachments/hdap/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](rest-operations.html#query-parameters):

* Curl

* JavaScript

* Python

* Ruby

```console
$ 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'
```

> **Collapse: Show output**
>
> ```
> {
>   "_id" : "dc=com/dc=example/ou=People/uid=bjensen",
>   "_rev" : "<revision>",
>   "mail" : [ "bjensen@example.com" ],
>   "cn" : [ "Barbara Jensen", "Babs Jensen" ]
> }
> ```

```javascript
(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](../_attachments/hdap/js/read-fields.js), [utils.js](../_attachments/hdap/js/utils.js)

```python
#!/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](../_attachments/hdap/py/utils.py), [read-fields.py](../_attachments/hdap/py/read-fields.py)

```ruby
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](../_attachments/hdap/rb/utils.rb), [read-fields.rb](../_attachments/hdap/rb/read-fields.rb)

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