DCL API by cecille · Pull Request #123 · project-chip/matter-handbook

cecille · 2026-01-18T02:51:20Z

No description provided.

github-actions · 2026-01-18T02:52:03Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

gemini-code-assist

Code Review

This pull request introduces a new, well-structured API reference page for the DCL and links to it from the main DCL documentation. The new page provides a helpful overview of the DCL REST API. My review includes suggestions to enhance the consistency and completeness of this new documentation, such as shortening lengthy section titles for better readability, adding missing JSON response examples to provide a more comprehensive guide for developers, and correcting a minor formatting inconsistency.

github-actions · 2026-01-18T22:17:08Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

github-actions · 2026-01-19T14:05:57Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

github-actions · 2026-01-19T15:26:22Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

github-actions · 2026-01-19T20:44:50Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

github-actions · 2026-01-19T21:01:28Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

github-actions · 2026-01-22T04:26:55Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

github-actions · 2026-01-22T04:28:37Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

cecille · 2026-01-19T20:59:58Z

+
+### REST API
+*   **Query All Root Certificates:** `/dcl/pki/root-certificates`
+    *   **Returns:** The list of all approved PAA certificates.


Q for DCL folks - are the signing keys for the CDs also in here?

Private keys are never put on chain.

Bad phrasing - what I was attempting to ask was whether the certificates for the CD signing keys in this portion of the DCL.

cecille · 2026-01-22T04:24:25Z

+**Description:** Provides the list of Operational Root CA Certificates (RCAC) and Operational Intermediate CA Certificates (ICAC).
+
+### REST API
+*   **Status:** Under Development


Q for the DCL folks - I think this might correspond to the noc-root-certificates / noc-ica-certificates, but there are some missing fields.

It's also not clear how the -vid- tables factor in here.

vid-specific queries are just helper queries to query RCACs/ICACs by VID (instead of common querying by subject/SKID as in Device Attestation certificates).
Please see #123 (comment) for details.

github-actions · 2026-01-28T18:11:02Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

Abdulbois · 2026-01-29T14:17:22Z

+
+## Operational Trust Anchors Schema
+**Description:** Provides the list of Operational Root CA Certificates (RCAC) and Operational Intermediate CA Certificates (ICAC).
+


Rest endpoint for this is /dcl/pki/noc-ica-certificates

Returns the list of all RCAC and ICAC certificates and associated Vendor ID

Pagination is required

To query by Vendor id the following endpoint /dcl/pki/noc-vid-ica-certificates/{vid} can be used

Returns the list of RCAC and ICAC certificates and associated Vendor ID

Pagination is not applicable

The JSON ref for that doesn't match the spec description. It lists
"certificateType": "DeviceAttestationPKI",

and is missing the IsVidVerificationSigner. The name matches, but this doesn't seem like an implementation of that spec schema.

Please see #123 (comment)

ashcherbakov · 2026-01-29T14:08:59Z

+---
+
+## Additional Schemas & Indices
+


We may also mention /dcl/pki/all-certificates/.... endpoints which return both DA and NOC based certificates.

ashcherbakov · 2026-01-29T14:12:39Z

+---
+
+## Operational Trust Anchors Schema
+**Description:** Provides the list of Operational Root CA Certificates (RCAC) and Operational Intermediate CA Certificates (ICAC).


Looks like exact endpoints are not mentioned here:

/dcl/pki/all-noc-certificates

/dcl/pki/all-noc-certificates/{subject}

/dcl/pki/all-noc-certificates/{subject}/{subject_key_id}

/dcl/pki/noc-vid-root-certificates/{vid}

/dcl/pki/noc-vid-certificates/{vid}/{subject_key_id}

/dcl/pki/noc-ica-certificates

/dcl/pki/noc-vid-ica-certificates/{vid}

See comment below - it's not clear to me how these relate to the spec schema and they're currently unpopulated. I'm going to leave this as a follow up for the DCL team because I genuinely don't understand the division of mapping here. This should be written by someone who can properly explain it.

All the endpoints I mentioned are for the schema https://github.com/CHIP-Specifications/connectedhomeip-spec/blob/master/src/service_device_management/DistributedComplianceLedger.adoc#5-operational-trust-anchors-schema.

NOC == Operational Trust Anchors (so all-noc means bothRCAC and ICAC)

RCAC == noc-root

ICAC == noc-ica

vid-specific queries are just helper queries to query RCACs/ICACs by VID (instead of common querying by subject/SKID as in Device Attestation certificates).

As part of the current task to review changes between DCL implementation and the spec, we are going to clarify the details and either fix the difference between the spec and the code, or provided better mapping/clarifications.

OK, until that point, I would hesitate to document this endpoint as implementing the spec schema. If the DCL team wants to come back later update this section, that should be done after the cleanup.

I would prefer to leave this to the DCL team to update once those fixes are made.

ashcherbakov · 2026-01-29T14:13:34Z

+*   **Query by Subject & SubjectKeyID:** `/dcl/pki/certificates/{subject}/{subjectKeyId}`
+    *   **Returns:** A specific certificate.
+    *   **Pagination:** Not applicable.
+    * NOTE - subject needs to be percent formatted, which is a transformation of the data returned from the base root-certificates request.


We may also mention

/dcl/pki/certificates?subjectKeyId={subjectKeyId}

/dcl/pki/certificates/{subject}

ashcherbakov · 2026-01-29T14:15:19Z

+
+*   **Query by VID, PID & Software Version:** `/dcl/compliance/certified-models/{vid}/{pid}/{softwareVersion}/{certificationType}`
+    *   **Returns:** A boolean-like record indicating if the specific version is certified.
+


We may also mention revoked models:

/dcl/compliance/revoked-models

/dcl/compliance/revoked-models/{vid}/{pid}/{software_version}/{certification_type}

Right now there are no revoked models, and I'm not sure exactly what the corresponds to in the spec. I'd rather leave that as a follow up until a person from the DCL team can come and explain how that actually relates to the spec and what's intended to be in there.

It's perhaps one of the DCL feature which is not mentioned explicitly in the spec. Will be updated as part of the current Spec Compliance task.

OK, let's leave this as is, and it can be added to this documentation once the spec work is done.

ashcherbakov · 2026-01-29T14:20:08Z

+
+### Web Interface
+*   **Location:** Accessed via the **Models** view details page.
+


There is also a way to return a list of Compliance records by cDCertificateId:
/dcl/compliance/device-software-compliance/{cDCertificateId}

Abdulbois · 2026-01-29T14:33:45Z

+
+*   **Query by VID:** `/dcl/model/models/{vid}`
+    *   **Returns:** All models associated with a specific Vendor ID.
+    *   **Pagination:** **Required**.


Suggested change

* **Pagination:** **Required**.

* **Pagination:** **Not applicable**.

Oh, is there actually not pagination there? There are definitely vendors with more than 100 models. How do those work?

Currently that endpoint does not return models but vendor products(which contains info about name, partNumber and pid).

I hope in the upcoming release that should be changed to return all models associated with Vendor ID

I think we're just using different words since the spec and the implementation wording is different. This endpoint returns information about vendor products. There are some vendors that have > 100 products. So are they all returned or are the results truncated?

Yes, it returns all vendor products at once

I don't understand the differentiation between models and products here. Can you explain the difference? The endpoint name is models, but that seems to be a reference to the various PIDs. These terms seen interchangeable.

Abdulbois · 2026-01-29T14:51:55Z

+    * NOTE - `vid` (Vendor ID) is a decimal value
+
+*   **Query by VID & PID:** `/dcl/model/models/{vid}/{pid}`
+    *   **Returns:** Details for a specific product.


Maybe

Suggested change

* **Returns:** Details for a specific product.

* **Returns:** Details for a specific device model.

what is a device mode here? That seems like a DCL term.

I believe Device Model is a term from the spec, and the name of the Schema: https://github.com/CHIP-Specifications/connectedhomeip-spec/blob/master/src/service_device_management/DistributedComplianceLedger.adoc#6-devicemodel-schema

yes, and those relate "A unique combination of the VendorID and ProductID is used to identify a DeviceModel." So product and device model seem interchangeable in this context. Why is product incorrect here?

Co-authored-by: Abdulbois <30406506+Abdulbois@users.noreply.github.com>

github-actions · 2026-01-29T14:58:28Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

github-actions · 2026-01-29T15:39:06Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

github-actions · 2026-01-29T15:48:02Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

Co-authored-by: Abdulbois <30406506+Abdulbois@users.noreply.github.com>

github-actions · 2026-02-05T21:40:15Z

Preview deployed at https://d2doqw88td69eq.cloudfront.net/pr-123

DCL API

ec288c8

gemini-code-assist Bot reviewed Jan 18, 2026

View reviewed changes

Comment thread src/en/guides/dcl/api_reference.md Outdated

Comment thread src/en/guides/dcl/api_reference.md Outdated

Comment thread src/en/guides/dcl/api_reference.md Outdated

Comment thread src/en/guides/dcl/api_reference.md Outdated

Comment thread src/en/guides/dcl/api_reference.md Outdated

add json references

38c42fa

Update src/en/guides/dcl/api_reference.md

8de4f68

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

cecille added 3 commits January 19, 2026 15:25

Move non-spec tables to the bottom

ba618bf

Update order to match spec

80019d7

Add a section for Operational Trust Anchors

f755eb5

cecille commented Jan 19, 2026

View reviewed changes

Comment thread src/en/guides/dcl/api_reference.md Outdated

Comment thread src/en/guides/dcl/api_reference.md Outdated

Comment thread src/en/guides/dcl/api_reference.md Outdated

cecille added 3 commits January 19, 2026 23:45

first go at fields

0a18fa6

checkpoint

d8fb134

remove json, refer to API page

c6dbe62

cecille force-pushed the dcl_api branch from 34f8cf7 to c6dbe62 Compare January 22, 2026 04:26

spelling

2011269

cecille changed the title ~~[WIP - not yet ready, want to see preview] DCL API~~ DCL API Jan 22, 2026

cecille marked this pull request as ready for review January 22, 2026 04:30

backticks

ee830ba

cecille commented Jan 28, 2026

View reviewed changes

Abdulbois reviewed Jan 29, 2026

View reviewed changes

ashcherbakov reviewed Jan 29, 2026

View reviewed changes

Abdulbois reviewed Jan 29, 2026

View reviewed changes

Comment thread src/en/guides/dcl/api_reference.md Outdated

Abdulbois reviewed Jan 29, 2026

View reviewed changes

Update src/en/guides/dcl/api_reference.md

8755eee

Co-authored-by: Abdulbois <30406506+Abdulbois@users.noreply.github.com>

cecille commented Jan 29, 2026

View reviewed changes

Comment thread src/en/guides/dcl/api_reference.md Outdated

Update src/en/guides/dcl/api_reference.md

1df5b1b

cecille commented Jan 29, 2026

View reviewed changes

Comment thread src/en/guides/dcl/api_reference.md Outdated

Update src/en/guides/dcl/api_reference.md

54850cf

Abdulbois reviewed Jan 29, 2026

View reviewed changes

Comment thread src/en/guides/dcl/api_reference.md

Abdulbois reviewed Jan 29, 2026

View reviewed changes

Comment thread src/en/guides/dcl/api_reference.md

Abdulbois reviewed Jan 29, 2026

View reviewed changes

Comment thread src/en/guides/dcl/api_reference.md Outdated

Update src/en/guides/dcl/api_reference.md

a08c25d

Co-authored-by: Abdulbois <30406506+Abdulbois@users.noreply.github.com>


		## Operational Trust Anchors Schema
		Description: Provides the list of Operational Root CA Certificates (RCAC) and Operational Intermediate CA Certificates (ICAC).


		* Query by VID, PID & Software Version: `/dcl/compliance/certified-models/{vid}/{pid}/{softwareVersion}/{certificationType}`
		* Returns: A boolean-like record indicating if the specific version is certified.


		### Web Interface
		* Location: Accessed via the Models view details page.

	* Pagination: Required.
	* Pagination: Not applicable.

	* Returns: Details for a specific product.
	* Returns: Details for a specific device model.

Uh oh!

Conversation

cecille commented Jan 18, 2026

Uh oh!

github-actions Bot commented Jan 18, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jan 18, 2026

Uh oh!

github-actions Bot commented Jan 19, 2026

Uh oh!

github-actions Bot commented Jan 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jan 19, 2026

Uh oh!

github-actions Bot commented Jan 19, 2026

Uh oh!

github-actions Bot commented Jan 22, 2026

Uh oh!

github-actions Bot commented Jan 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jan 28, 2026

Uh oh!

Abdulbois Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cecille Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ashcherbakov Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Abdulbois Jan 29, 2026 •

edited

Loading

cecille Jan 29, 2026 •

edited

Loading

ashcherbakov Feb 5, 2026 •

edited

Loading

Abdulbois Jan 29, 2026 •

edited

Loading