--- title: Learn REST/HTTP description: The examples that follow show you how to send RESTful HTTP requests to the directory server. component: pingds version: 7.2 page_id: pingds:getting-started:rest canonical_url: https://docs.pingidentity.com/pingds/8.1/getting-started/rest.html llms_txt: https://docs.pingidentity.com/pingds/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2021-02-26T14:04:33Z superseded_by: https://docs.pingidentity.com/pingds/8.1/getting-started/rest.html section_ids: before-rest: Prepare create-rest: Create read-rest: Read update-rest: Update delete-rest: Delete --- # Learn REST/HTTP The examples that follow show you how to send RESTful HTTP requests to the directory server. Before you try the examples, set up a server, as described in [Install DS](install.html). > **Collapse: More about HTTP access** > > ForgeRock Directory Services let you access directory data over HTTP as well as LDAP. The feature is known as REST to LDAP because it transforms REST operations into LDAP operations. > > The server maps JSON resources to LDAP entries in order to convert HTTP operations to LDAP internally. The directory server you installed is bundled with a default mapping file for sample data. You can configure your own mapping depending on your directory data, and the JSON objects you want. > > ![REST to LDAP translation between JSON resources and LDAP entries](../_images/rest2ldap.png) ## Prepare Get the deployment CA certificate used to trust the server in the RESTful examples: > **Collapse: (Bash, Zsh) Get the CA cert in PEM format** > > When using the Bash or Zsh examples with `curl` commands, get the deployment CA certificate in PEM format, which the `curl` command can read: > > * Bash > > * Zsh > > ```bash > $ dskeymgr \ > export-ca-cert \ > --deploymentId $DEPLOYMENT_ID \ > --deploymentIdPassword password \ > --outputFile ca-cert.pem > ``` > > ```zsh > % dskeymgr \ > export-ca-cert \ > --deploymentId $DEPLOYMENT_ID \ > --deploymentIdPassword password \ > --outputFile ca-cert.pem > ``` > **Collapse: (PowerShell) Import the CA certificate with MMC** > > For PowerShell examples, first configure Windows to trust the deployment CA certificate. Import the deployment CA from the server truststore using Microsoft Management Console (MMC): > > 1. Run Microsoft Management Console (`mmc.exe`). > > 2. Add the certificates snap-in so you can import the deployment CA certificate: > > * In the console, select File > Add/Remove Snap-in, then Add. > > * Select Certificates from the list of snap-ins and click Add. > > * Finish the wizard. > > 3. Import the deployment CA certificate using the snap-in: > > * Select Console Root > Trusted Root Certification Authorities > Certificates. > > * In the Action menu, select Import to open the wizard. > > * Use the wizard to import the deployment CA certificate from the server truststore file, `C:\path\to\opendj\config\keystore`. > > The truststore password is the text in the file `C:\path\to\opendj\config\keystore.pin`. ## Create Use the REST API to create a user resource over HTTP: * Bash * PowerShell * Zsh ```bash $ curl \ --request POST \ --cacert ca-cert.pem \ --user admin:password \ --header "Content-Type: application/json" \ --data '{ "_id": "newuser", "_schema":"frapi:opendj:rest2ldap:user:1.0", "contactInformation": { "telephoneNumber": "+1 408 555 1212", "emailAddress": "newuser@example.com" }, "name": { "givenName": "New", "familyName": "User" }, "displayName": ["New User"], "manager": { "_id": "bjensen", "displayName": "Babs Jensen" } }' \ https://localhost:8443/api/users?_prettyPrint=true { "_id" : "newuser", "_rev" : "", "_schema" : "frapi:opendj:rest2ldap:user:1.0", "_meta" : { "created" : "" }, "userName" : "newuser@example.com", "displayName" : [ "New User" ], "name" : { "givenName": "New", "familyName": "User" }, "manager" : { "_id" : "bjensen", "_rev" : "" }, "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" } } ``` ```powershell PS C:\path\to> $Credentials = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("admin:password")) $Headers = @{ Authorization = "Basic $Credentials" } Invoke-RestMethod ` -Uri https://localhost:8443/api/users ` -Method Post ` -Headers $Headers ` -ContentType application/json ` -Body @" { "_id": "newuser", "_schema":"frapi:opendj:rest2ldap:user:1.0", "contactInformation": { "telephoneNumber": "+1 408 555 1212", "emailAddress": "newuser@example.com" }, "name": { "givenName": "New", "familyName": "User" }, "displayName": ["New User"], "manager": { "_id": "bjensen", "displayName": "Babs Jensen" } } "@ | ConvertTo-JSON { "_id": "newuser", "_rev": "", "_schema": "frapi:opendj:rest2ldap:user:1.0", "_meta": { "created": "" }, "userName": "newuser@example.com", "displayName": [ "New User" ], "name": { "givenName": "New", "familyName": "User" }, "manager": { "_id": "bjensen", "_rev": "" }, "contactInformation": { "telephoneNumber": "+1 408 555 1212", "emailAddress": "newuser@example.com" } } ``` ```zsh % curl \ --request POST \ --cacert ca-cert.pem \ --user admin:password \ --header "Content-Type: application/json" \ --data '{ "_id": "newuser", "_schema":"frapi:opendj:rest2ldap:user:1.0", "contactInformation": { "telephoneNumber": "+1 408 555 1212", "emailAddress": "newuser@example.com" }, "name": { "givenName": "New", "familyName": "User" }, "displayName": ["New User"], "manager": { "_id": "bjensen", "displayName": "Babs Jensen" } }' \ "https://localhost:8443/api/users?_prettyPrint=true" { "_id" : "newuser", "_rev" : "", "_schema" : "frapi:opendj:rest2ldap:user:1.0", "_meta" : { "created" : "" }, "userName" : "newuser@example.com", "displayName" : [ "New User" ], "name" : { "givenName": "New", "familyName": "User" }, "manager" : { "_id" : "bjensen", "_rev" : "" }, "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" } } ``` > **Collapse: More about the example** > > * The command makes a secure connection to the server using HTTPS. > > * The user performing the HTTP POST is the directory superuser. > > The default authorization mechanism for HTTP access is HTTP Basic authentication. The superuser's HTTP user ID, `admin`, is mapped to the LDAP DN, `uid=admin`. REST to LDAP uses the DN and password to perform a simple LDAP bind for authentication. The directory can then use its LDAP-based access control mechanisms to authorize the operation. > > * The form of the JSON data respects the API defined by the mapping file. The example mapping file is a JSON format configuration file with comments. See `/path/to/opendj/config/rest2ldap/endpoints/api/example-v1.json` . > > * The successful response is the JSON resource that the command created. > > Fields whose names start with `_` are reserved. For details, see [DS REST APIs](../rest-guide/rest-operations.html). For additional details, see [DS REST APIs](../rest-guide/rest-operations.html) and [Create](../rest-guide/create-rest.html). ## Read Use the REST API to read the user resource created in [Create](#create-rest): * Bash * PowerShell * Zsh ```bash $ curl \ --request GET \ --cacert ca-cert.pem \ --user bjensen:hifalutin \ --header "Content-Type: application/json" \ https://localhost:8443/api/users/newuser?_prettyPrint=true { "_id" : "newuser", "_rev" : "", "_schema" : "frapi:opendj:rest2ldap:user:1.0", "_meta" : { "created" : "" }, "userName" : "newuser@example.com", "displayName" : [ "New User" ], "name" : { "givenName": "New", "familyName": "User" }, "manager" : { "_id" : "bjensen", "_rev" : "" }, "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" } } ``` ```powershell PS C:\path\to> $Credentials = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("bjensen:hifalutin")) $Headers = @{ Authorization = "Basic $Credentials" } Invoke-RestMethod ` -Uri https://localhost:8443/api/users/newuser ` -Method Get ` -Headers $Headers ` -ContentType application/json | ConvertTo-JSON { "_id": "newuser", "_rev": "", "_schema": "frapi:opendj:rest2ldap:user:1.0", "_meta": { "created": "" }, "userName": "newuser@example.com", "displayName": [ "New User" ], "name": { "givenName": "New", "familyName": "User" }, "manager": { "_id": "bjensen", "_rev": "" }, "contactInformation": { "telephoneNumber": "+1 408 555 1212", "emailAddress": "newuser@example.com" } } ``` ```zsh % curl \ --request GET \ --cacert ca-cert.pem \ --user bjensen:hifalutin \ --header "Content-Type: application/json" \ "https://localhost:8443/api/users/newuser?_prettyPrint=true" { "_id" : "newuser", "_rev" : "", "_schema" : "frapi:opendj:rest2ldap:user:1.0", "_meta" : { "created" : "" }, "userName" : "newuser@example.com", "displayName" : [ "New User" ], "name" : { "givenName": "New", "familyName": "User" }, "manager" : { "_id" : "bjensen", "_rev" : "" }, "contactInformation" : { "telephoneNumber" : "+1 408 555 1212", "emailAddress" : "newuser@example.com" } } ``` Notice that Babs Jensen authenticates for this HTTP GET request. If no credentials are specified, the response is the HTTP 401 Unauthorized: ```json {"code":401,"reason":"Unauthorized","message":"Invalid Credentials"} ``` In other words, the HTTP Basic authorization mechanism requires authentication even for read operations. For additional details, see [DS REST APIs](../rest-guide/rest-operations.html) and [Read](../rest-guide/read-rest.html). You can also query collections of resources, as described in [Query](../rest-guide/query-rest.html). ## Update Use the REST API to replace the user resource created in [Create](#create-rest): * Bash * PowerShell * Zsh ```bash $ curl \ --request PUT \ --cacert ca-cert.pem \ --user admin:password \ --header "Content-Type: application/json" \ --header "If-Match: *" \ --data '{ "_id": "newuser", "_schema":"frapi:opendj:rest2ldap:user:1.0", "contactInformation": { "telephoneNumber": "+1 234 567 8910", "emailAddress": "updated.user@example.com" }, "name": { "givenName": "Updated", "familyName": "User" }, "displayName": ["Updated User"], "manager": { "_id" : "bjensen", "displayName" : "Babs Jensen" } }' \ https://localhost:8443/api/users/newuser?_prettyPrint=true { "_id" : "newuser", "_rev" : "", "_schema" : "frapi:opendj:rest2ldap:user:1.0", "_meta" : { "created" : "", "lastModified" : "" }, "displayName" : [ "Updated User" ], "name" : { "givenName" : "Updated", "familyName" : "User" }, "manager" : { "_id" : "bjensen", "_rev" : "" }, "contactInformation" : { "telephoneNumber" : "+1 234 567 8910" } } ``` ```powershell PS C:\path\to> $Credentials = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("admin:password")) $Headers = @{ "Authorization" = "Basic $Credentials" "If-Match" = "*" } Invoke-RestMethod ` -Uri https://localhost:8443/api/users/newuser ` -Method Put ` -Headers $Headers ` -ContentType application/json ` -Body @" { "_id": "newuser", "_schema":"frapi:opendj:rest2ldap:user:1.0", "contactInformation": { "telephoneNumber": "+1 234 567 8910", "emailAddress": "updated.user@example.com" }, "name": { "givenName": "Updated", "familyName": "User" }, "displayName": ["Updated User"], "manager": { "_id" : "bjensen", "displayName" : "Babs Jensen" } } "@ | ConvertTo-JSON { "_id": "newuser", "_rev": "", "_schema": "frapi:opendj:rest2ldap:user:1.0", "_meta": { "created": "", "lastModified": "" }, "displayName": [ "Updated User" ], "name": { "givenName": "Updated", "familyName": "User" }, "manager": { "_id": "bjensen", "_rev": "" }, "contactInformation": { "telephoneNumber": "+1 234 567 8910" } } ``` ```zsh % curl \ --request PUT \ --cacert ca-cert.pem \ --user admin:password \ --header "Content-Type: application/json" \ --header "If-Match: *" \ --data '{ "_id": "newuser", "_schema":"frapi:opendj:rest2ldap:user:1.0", "contactInformation": { "telephoneNumber": "+1 234 567 8910", "emailAddress": "updated.user@example.com" }, "name": { "givenName": "Updated", "familyName": "User" }, "displayName": ["Updated User"], "manager": { "_id" : "bjensen", "displayName" : "Babs Jensen" } }' \ "https://localhost:8443/api/users/newuser?_prettyPrint=true" { "_id" : "newuser", "_rev" : "", "_schema" : "frapi:opendj:rest2ldap:user:1.0", "_meta" : { "created" : "" }, "userName" : "newuser@example.com", "displayName" : [ "Updated User" ], "name" : { "givenName" : "Updated", "familyName" : "User" }, "manager" : { "_id" : "bjensen", "_rev" : "" }, "contactInformation" : { "telephoneNumber" : "+1 234 567 8910", "emailAddress" : "updated.user@example.com" } } ``` Resources are versioned using revision numbers. A revision is specified in the resource's `\_rev` field. The `--header "If-Match: *"` ensures the resource is replaced, regardless of its revision. Alternatively, you can set `--header "If-Match: revision"` to replace only the expected revision of the resource. For additional details, see [DS REST APIs](../rest-guide/rest-operations.html) and [Update](../rest-guide/update-rest.html). You can also patch resources instead of replacing them entirely. See [Patch](../rest-guide/patch-rest.html). ## Delete Use the REST API to delete the user resource updated in [Update](#update-rest): * Bash * PowerShell * Zsh ```bash $ curl \ --request DELETE \ --cacert ca-cert.pem \ --user admin:password \ --header "Content-Type: application/json" \ https://localhost:8443/api/users/newuser?_prettyPrint=true { "_id" : "newuser", "_rev" : "", "_schema" : "frapi:opendj:rest2ldap:user:1.0", "_meta" : { "created" : "", "lastModified" : "" }, "displayName" : [ "Updated User" ], "name" : { "givenName" : "Updated", "familyName" : "User" }, "manager" : { "_id" : "bjensen", "_rev" : "" }, "contactInformation" : { "telephoneNumber" : "+1 234 567 8910" } } ``` ```powershell PS C:\path\to> $Credentials = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("admin:password")) $Headers = @{ Authorization = "Basic $Credentials" } Invoke-RestMethod ` -Uri https://localhost:8443/api/users/newuser ` -Method Delete ` -Headers $Headers ` -ContentType application/json | ConvertTo-JSON { "_id": "newuser", "_rev": "", "_schema": "frapi:opendj:rest2ldap:user:1.0", "_meta": { "created": "", "lastModified": "" }, "displayName": [ "Updated User" ], "name": { "givenName": "Updated", "familyName": "User" }, "manager": { "_id": "bjensen", "_rev": "" }, "contactInformation": { "telephoneNumber": "+1 234 567 8910" } } ``` ```zsh % curl \ --request DELETE \ --cacert ca-cert.pem \ --user admin:password \ --header "Content-Type: application/json" \ "https://localhost:8443/api/users/newuser?_prettyPrint=true" { "_id" : "newuser", "_rev" : "", "_schema" : "frapi:opendj:rest2ldap:user:1.0", "_meta" : { "created" : "" }, "userName" : "newuser@example.com", "displayName" : [ "Updated User" ], "name" : { "givenName" : "Updated", "familyName" : "User" }, "manager" : { "_id" : "bjensen", "_rev" : "" }, "contactInformation" : { "telephoneNumber" : "+1 234 567 8910", "emailAddress" : "updated.user@example.com" } } ``` For additional details, see [DS REST APIs](../rest-guide/rest-operations.html) and [Delete](../rest-guide/delete-rest.html).