Add list resources API support by miewest · Pull Request #129 · cyberark/conjur-api-java

miewest · 2026-03-03T18:03:10Z

Closes #128
Builds on #127

Summary

Adds support for the Conjur List Resources API (GET /resources/{account}) to the Java SDK. This builds on the Endpoints refactor and infrastructure introduced in #127 (batch secret retrieval).

Changes

New files

ConjurResource.java — Model class for resources returned by the API. Includes fields for id, created_at, owner, policy, permissions, annotations, secrets, and policy_versions. Inner classes Permission and Annotation for nested objects. Helper methods getKind() and getIdentifier() to parse the {account}:{kind}:{identifier} resource ID format.

Modified files

Endpoints.java — Added getResourcesUri() returning {applianceUrl}/resources/{account}
ResourceProvider.java — Added listResources() (3 overloads) and countResources() as default interface methods for backward compatibility
ResourceClient.java — Full HTTP implementation: builds query parameters (kind, search, limit, offset, count), parses JSON arrays via Gson into List<ConjurResource>, handles both JSON {"count":N} and plain integer count response formats
Variables.java — Delegation to ResourceClient
Conjur.java — Convenience methods on the entry point class
ResourceClientTest.java — 17 new unit tests covering: list all resources, filter by kind, text search, pagination, combined parameters, empty results, 401/403 error handling, full field parsing (permissions, annotations), special character encoding in search, count with JSON format, count with plain integer format, count by kind, count with search, count 401 error, and Endpoints URI derivation

API

Conjur conjur = new Conjur();

// List all visible resources
List<ConjurResource> all = conjur.listResources();

// Filter by kind
List<ConjurResource> vars = conjur.listResources("variable");

// Search with pagination
List<ConjurResource> page = conjur.listResources("variable", "prod", 100, 0);

// Count resources
int count = conjur.countResources("variable", null);

// Access resource fields
ConjurResource r = vars.get(0);
r.getId();          // "myaccount:variable:path/to/secret"
r.getKind();        // "variable"
r.getIdentifier();  // "path/to/secret"
r.getOwner();       // "myaccount:policy:root"
r.getPermissions(); // List<Permission>
r.getAnnotations(); // List<Annotation>

Testing

45 unit tests pass (44 ResourceClientTest + 1 TelemetryHeaderTest)
Tested against a live Conjur server: list all, filter by kind (variable/host/policy), text search, pagination (limit/offset), count, and count-vs-list consistency check all pass

- Implemented batch secret retrieval methods in ResourceClient, Variables, and ResourceProvider. - Enhanced Endpoints class to support batch retrieval URI. - Added comprehensive unit tests for batch secret retrieval in ResourceClientTest.

miewest · 2026-03-03T18:08:59Z

Like the other PR, I also created a manual full integration test of this code but wasn't sure if it fit in the repo. I can add it if wanted.

szh · 2026-03-05T15:44:07Z

Thank you for the PR! We've added it to our backlog to review.

Tracking internally as CNJR-13116.

dondany · 2026-03-20T10:18:26Z

src/main/java/com/cyberark/conjur/api/Endpoints.java

    private final URI authnUri;
    private final URI secretsUri;

-    public Endpoints(final URI authnUri, final URI secretsUri){


Old constructors should stay as mentioned on the other PR for the batch secrets retrival:
#127 (comment)

dondany · 2026-03-20T10:18:32Z

src/main/java/com/cyberark/conjur/api/Endpoints.java

+        this(applianceUrl, account, applianceUrl + "/authn");
    }

-    public Endpoints(String authnUri, String secretsUri){


Same as above

dondany · 2026-03-20T10:21:46Z

src/main/java/com/cyberark/conjur/api/Conjur.java

+
+    /**
+     * Fetch multiple secret values in one invocation.
+     *
+     * @param variableIds the variable IDs to retrieve
+     * @return a map of variable ID to secret value
+     */
+    public Map<String, String> retrieveBatchSecrets(String... variableIds) {
+        return variables.retrieveBatchSecrets(variableIds);
+    }
+
+    /**
+     * List all resources visible to the authenticated identity.
+     *
+     * @return list of all resources
+     */
+    public List<ConjurResource> listResources() {
+        return variables.listResources();
+    }
+
+    /**
+     * List resources filtered by kind.
+     *
+     * @param kind the resource kind (e.g. "variable", "host")
+     * @return resources matching the given kind
+     */
+    public List<ConjurResource> listResources(String kind) {
+        return variables.listResources(kind);
+    }
+
+    /**
+     * List resources with full query parameter control.
+     *
+     * @param kind   resource kind filter (null for all kinds)
+     * @param search text search filter (null for no search)
+     * @param limit  max results (null for server default)
+     * @param offset pagination offset (null for no offset)
+     * @return resources matching the query
+     */
+    public List<ConjurResource> listResources(String kind, String search, Integer limit, Integer offset) {
+        return variables.listResources(kind, search, limit, offset);
+    }
+
+    /**
+     * Count resources visible to the authenticated identity.
+     *
+     * @param kind   resource kind filter (null for all kinds)
+     * @param search text search filter (null for no search)
+     * @return the number of matching resources
+     */
+    public int countResources(String kind, String search) {
+        return variables.countResources(kind, search);
+    }


All the methods seem to be unnecessary shortcuts. These should be accessed through for example variables

dondany · 2026-03-20T10:25:21Z

src/main/java/com/cyberark/conjur/api/Variables.java

+    public List<ConjurResource> listResources() {
+        return resourceClient.listResources();
+    }
+
+    /**
+     * List resources filtered by kind.
+     *
+     * @param kind the resource kind (e.g. "variable", "host")
+     * @return resources matching the given kind
+     */
+    public List<ConjurResource> listResources(String kind) {
+        return resourceClient.listResources(kind);
+    }
+
+    /**
+     * List resources with full query parameter control.
+     *
+     * @param kind   resource kind filter (null for all kinds)
+     * @param search text search filter (null for no search)
+     * @param limit  max results (null for server default)
+     * @param offset pagination offset (null for no offset)
+     * @return resources matching the query
+     */
+    public List<ConjurResource> listResources(String kind, String search, Integer limit, Integer offset) {
+        return resourceClient.listResources(kind, search, limit, offset);
+    }
+
+    /**
+     * Count resources visible to the authenticated identity.
+     *
+     * @param kind   resource kind filter (null for all kinds)
+     * @param search text search filter (null for no search)
+     * @return the number of matching resources
+     */
+    public int countResources(String kind, String search) {
+        return resourceClient.countResources(kind, search);
+    }


As these methods are not specifically about the variables, maybe it would be a good idea to move them to a separate class i.e. Resources and manage it in Conjur class just like Variables.

dondany · 2026-03-20T10:44:12Z

src/main/java/com/cyberark/conjur/api/clients/ResourceClient.java

+    /**
+     * List all resources visible to the authenticated identity.
+     *
+     * @return list of all resources
+     * @see <a href="https://docs.cyberark.com/conjur-open-source/latest/en/content/developer/conjur_api_list_resources.htm">List Resources</a>
+     */
+    @Override
+    public List<ConjurResource> listResources() {
+        return listResources(null, null, null, null);
+    }
+
+    /**
+     * List resources filtered by kind.
+     *
+     * @param kind the resource kind (e.g. "variable", "host", "user", "group", "layer", "policy", "webservice")
+     * @return resources matching the given kind
+     */
+    @Override
+    public List<ConjurResource> listResources(String kind) {
+        return listResources(kind, null, null, null);
+    }
+
+    /**
+     * List resources with full query parameter control.
+     *
+     * @param kind   resource kind filter (null for all kinds)
+     * @param search text search filter (null for no search)
+     * @param limit  max results per page (null for server default, max 1000)
+     * @param offset pagination offset (null for no offset)
+     * @return resources matching the query
+     * @throws WebApplicationException if the server returns an error response
+     */
+    @Override
+    public List<ConjurResource> listResources(String kind, String search, Integer limit, Integer offset) {
+        URI resourcesUri = endpoints.getResourcesUri();
+        StringBuilder uriBuilder = new StringBuilder(resourcesUri.toString());
+        String separator = "?";
+
+        if (kind != null && !kind.isEmpty()) {
+            uriBuilder.append(separator).append("kind=").append(encodeVariableId(kind));
+            separator = "&";
+        }
+        if (search != null && !search.isEmpty()) {
+            uriBuilder.append(separator).append("search=").append(encodeVariableId(search));
+            separator = "&";
+        }
+        if (limit != null) {
+            uriBuilder.append(separator).append("limit=").append(limit);
+            separator = "&";
+        }
+        if (offset != null) {
+            uriBuilder.append(separator).append("offset=").append(offset);
+        }
+
+        URI targetUri = URI.create(uriBuilder.toString());
+        Response response = client.target(targetUri).request().get(Response.class);
+        validateResponse(response);
+
+        String json = response.readEntity(String.class);
+        List<ConjurResource> resources = GSON.fromJson(json, LIST_RESOURCE_TYPE);
+        return resources != null ? resources : Collections.<ConjurResource>emptyList();
+    }
+
+    /**
+     * Count resources visible to the authenticated identity.
+     *
+     * @param kind   resource kind filter (null for all kinds)
+     * @param search text search filter (null for no search)
+     * @return the number of matching resources
+     * @throws WebApplicationException if the server returns an error response
+     */
+    @Override
+    public int countResources(String kind, String search) {
+        URI resourcesUri = endpoints.getResourcesUri();
+        StringBuilder uriBuilder = new StringBuilder(resourcesUri.toString());
+        uriBuilder.append("?count=true");
+
+        if (kind != null && !kind.isEmpty()) {
+            uriBuilder.append("&kind=").append(encodeVariableId(kind));
+        }
+        if (search != null && !search.isEmpty()) {
+            uriBuilder.append("&search=").append(encodeVariableId(search));
+        }
+
+        URI targetUri = URI.create(uriBuilder.toString());
+        Response response = client.target(targetUri).request().get(Response.class);
+        validateResponse(response);
+
+        String body = response.readEntity(String.class).trim();
+
+        // The server may return a plain integer or a JSON object like {"count":N}
+        if (body.startsWith("{")) {
+            @SuppressWarnings("unchecked")
+            Map<String, Double> parsed = GSON.fromJson(body, Map.class);
+            Double count = parsed.get("count");
+            if (count == null) {
+                throw new IllegalStateException("Unexpected count response: " + body);
+            }
+            return count.intValue();
+        }
+        return Integer.parseInt(body);
+    }


These methods could probably be condensed into just 2.
One for searching/listing resources and the other for counting them.

The listResources(String kind, String search, Integer limit, Integer offset) signature is already at 4 nullable params and from what I've seen the underlying API supports more filters.
Every new param will require a signature change here, in ResourceClient, Variables, and anywhere these are called.

I'd suggest introducing a kind of value object ResourceQueryParameters (or whatever better name You can think of) that would aggregate all the possible search params that conjur API supports(except. count) and adding a method like:

List<ConjurResource> listResources(ResourceQueryParameters params);

There could be a mapper that maps ResourceQueryParameters into an URL. So if there is any new param to be addded in the future, the signature of the method won't change, only the ResourceQueryParameters and a mapper would be affected.

For the counting method We could have:

int countResources(ResourceQueryParameters params);

This one would take the same QueryParams and build the URL with the count = true. It would also separate the dirty(but totally necessary due to the API specs) logic of mapping the count response json.

This would make the code easier to maintain, and the users of the api would be able to build their own ResourceQueryParameters instances with whatever params they like. With a builder pattern for the ResourceQueryParameters implemented it could be really nice to use.

dondany · 2026-03-20T10:47:03Z

Please add some usage examples to the Readme as well.

dondany · 2026-03-20T10:50:49Z

You might also take a look at https://github.com/cyberark/conjur-sdk-java which is an OpenApi spec driven api, if it contains the needed functionalities.

dondany · 2026-03-27T07:27:28Z

FYI We have some capacity that allows us to work on this and the PR 127

miewest added 2 commits March 2, 2026 18:05

Add list resources API support

88bb2d9

dondany suggested changes Mar 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add list resources API support#129

Add list resources API support#129
miewest wants to merge 2 commits intocyberark:mainfrom
miewest:feature/list-resources

miewest commented Mar 3, 2026 •

edited

Loading

Uh oh!

miewest commented Mar 3, 2026

Uh oh!

szh commented Mar 5, 2026

Uh oh!

dondany Mar 20, 2026

Uh oh!

dondany Mar 20, 2026

Uh oh!

dondany Mar 20, 2026

Uh oh!

dondany Mar 20, 2026

Uh oh!

dondany Mar 20, 2026

Uh oh!

dondany commented Mar 20, 2026

Uh oh!

dondany commented Mar 20, 2026

Uh oh!

dondany commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

miewest commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New files

Modified files

API

Testing

Uh oh!

miewest commented Mar 3, 2026

Uh oh!

szh commented Mar 5, 2026

Uh oh!

dondany Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

dondany Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

dondany Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

dondany Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

dondany Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

dondany commented Mar 20, 2026

Uh oh!

dondany commented Mar 20, 2026

Uh oh!

dondany commented Mar 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

miewest commented Mar 3, 2026 •

edited

Loading