Skip to content

REST Channel

  • Request

    Choose an entry type and an optional filter.

  • Result

    Read the entries and follow the next page when needed.

A REST request returns directory entries as JSON.

You can enable REST, send a first request and recognize the response.

Next: API access

Standard HTTP/JSON. If your app can make a GET request, it can query the directory. The REST channel comes with an OpenAPI spec, interactive docs, conditional requests, and streaming exports.

The REST channel is disabled by default. Enable it to serve the data routes:

channels.rest.enabled = true

Key endpoints:

URLWhat you get
/apiOpenAPI UI (browser) or spec (JSON/YAML via content negotiation)
/api/entries/{type}Collection search
/api/entries/{type}/{id}Single entry lookup
/api/entries/{type}/{id}/changesPer-entry change history
/api/changesGlobal change feed
/api/changes/hotMost active entries in a time window

Browse /api in a browser for interactive API docs with code samples, live testing, and schema details. Download the spec at /api.json or /api.yaml.

REST paths and OpenAPI identifiers are derived from entry type names using singular/plural normalization. Startup enforces strict uniqueness across:

  • REST paths (/api/entries/{type}, /api/entries/{type}/{id}, /api/entries/{type}/{id}/changes)
  • OpenAPI operationId values (search*, lookup*, get*Changes)
  • OpenAPI schema component names (Entry_*, SearchResponse_*)

If two configured types collide after normalization (for example user and users), startup fails before serving traffic.

OpenAPI component names are sanitized to a conservative format for code generators: ^[A-Za-z][A-Za-z0-9_]*$. Reserved tokens (for example class) are suffixed (for example class_type). If sanitization causes a component-name collision, startup fails.

Filters auto-detect format. Use whichever fits your context:

FormatDetectionExample
JSONStarts with { or [{"cn":"john"}
LDAPStarts with ((cn=john*)
FleXDefaultcn = john
SCIMFallbackcn eq "john"
Terminal window
# Spaces in filter values are URL-encoded by curl when using --data-urlencode,
# or quote the entire URL as shown here
curl "/api/entries/users?filter=department%3DEngineering%20AND%20active%3Dtrue"
ValueReturns
cn,mail,snSpecific attributes
*All user attributes
+All operational attributes
1.1No attributes (IDs only)
Terminal window
?sort=cn # Ascending
?sort=-cn # Descending
?sort=sn,-cn # Multiple keys

When include, fields, sort, or pagination size are omitted, REST uses channels.rest.default-include, channels.rest.default-fields, channels.rest.default-sort, and channels.rest.default-limit. These inherit the shared query.* defaults unless the REST channel overrides them.

Relay-style cursor pagination:

ParameterDirection
first / afterForward
last / beforeBackward
limitAlias — resolves to first or last based on cursor
First requestfirst=25Page 1endCursor: eyJj…Next requestfirst=25&after=eyJj…Page 2next 25 entriesreturnsendCursor → afterreturns
First requestfirst=25Page 1endCursor: eyJj…Next requestfirst=25&after=eyJj…Page 2next 25 entriesreturnsendCursor → afterreturns
Send the previous page's endCursor as after to request the next page.
curl "/api/entries/users?first=25"
curl "/api/entries/users?first=25&after=eyJjbiI6Impv..."

The cursor is opaque: copy it as returned.

Lookup endpoints accept any identifier format. DN values must be URL-encoded in paths.

Poll a single entry efficiently with ETags:

LookupGET …/users/{id}200 OKETag: W/"abc…"Next lookupIf-None-Match304 Not Modifiedno body200 OKnew ETagreturnsETag → If-None-Matchunchangedchanged
LookupGET …/users/{id}200 OKETag: W/"abc…"Next lookupIf-None-Match304 Not Modifiedno body200 OKnew ETagreturnsETag → If-None-Matchunchangedchanged
A lookup that sends the previous ETag as If-None-Match returns 304 while the entry is unchanged.
curl -I "/api/entries/users/$UUID"
# ETag: W/"abc123..."
curl -H 'If-None-Match: W/"abc123..."' "/api/entries/users/$UUID"

If-Modified-Since is also supported. Search responses include Cache-Control: no-store; lookup responses include Cache-Control: private, max-age=0, must-revalidate.

Query changes via the global feed (/api/changes) or per-entry (/api/entries/{type}/{id}/changes).

To find entries with the most changes in a time window, use the hot-entries ranking:

Terminal window
# Top 20 most active entries in the last 24 hours
curl "/api/changes/hot?range=24h&first=20"
# MODIFY activity for users only, sorted by most recent change
curl "/api/changes/hot?range=7d&entryType=user&type=modify&sort=-lastTimestamp&first=10&include=pageInfo"
# Page forward using endCursor from pageInfo
curl "/api/changes/hot?range=24h&first=20&after=<cursor>&include=pageInfo"
Terminal window
# Changes in the last 24 hours
curl "/api/changes?range=24h&first=50"
# MODIFY events that changed the mail attribute
curl "/api/changes?type=modify&affects=mail&since=this week"

Time ranges accept temporal references: ISO timestamps, durations, yesterday, last 3 days, etc.

View an entry at any moment:

Terminal window
curl "/api/entries/users/$ID?at=2024-01-15T10:00:00Z"
curl "/api/entries/users/$ID?at=now-1h"

Change events support three data formats. Use ?include=nodes,patch,pageInfo to select which parts to return. For count-only queries (no data fetch), use ?include=count.

Stream search results to a file by adding filename (or the export options parameter) to any search request:

Search request/api/entries/usersOne pagefirst · after+ filenamefields=cn,mailusers.csvup to max-rowsreturnsadds filenamestreams every match
Search request/api/entries/usersOne pagefirst · after+ filenamefields=cn,mailusers.csvup to max-rowsreturnsadds filenamestreams every match
Adding filename streams every matching entry to a file instead of returning one page.
curl -OJ -G -d filename=users.csv \
-d fields=cn,mail,department "/api/entries/users"

An export ignores paging: first or limit only cap the number of rows, and the cursor parameters after, last and before are rejected. Every export stops at channels.rest.export.max-rows (100,000 rows by default).

FormatExtensionNotes
CSV.csvExcel-compatible, RFC 4180
TSV.tsvTab-delimited
JSON.jsonStreaming JSON array
NDJSON.ndjsonNewline-delimited JSON
JSON-seq.json-seqRFC 7464
JSON-LD.jsonldWith @id/@type
LDIF.ldifLDAP interchange format

Exports require an explicit field list — wildcards (*, +) are not allowed. Pass format options as JSON via the export parameter:

Terminal window
# Custom delimiter and null handling
curl -OJ '/api/entries/users?filename=data.csv&fields=cn,mail&export={"delimiter":"|","nulls":"N/A"}'

See Configuration Reference for export limits, delimited format options, and all other REST settings.

Control how the API handles unknown attributes with Prefer: handling=strict (returns 400 with the unknown names) or Prefer: handling=lenient (default — ignores unknowns silently).

See Signals for metrics, Error Handling for error codes.