# PID

The dPID system for research objects allows resolution to the underlying components in a consistent and granular way over HTTP and the IPFS network. You can learn more about the schema, syntax and variants below. Note that the system is under active development, and the specification is subject to change.

CID refers to Content Identifier according to the [Multiformats CID Specification](https://github.com/multiformats/cid)

## **dPID anatomy**

`HTTP URL = {Resolver}/{PID}/{version identifier OR CID}/{Component index}/{Component suffix}`

<table><thead><tr><th width="230">Component</th><th>Component Description</th></tr></thead><tbody><tr><td>Resolver</td><td>The <a href="https://en.wikipedia.org/wiki/Domain_Name_System">DNS</a> resolver, currently beta.dpid.org</td></tr><tr><td>PID</td><td>The registry's unique and version-invariant PID</td></tr><tr><td>Version identifier or CID</td><td>The version identifier (e.g. "v1" or "0") mapped to the CID of the manifest file or the manifest CID</td></tr><tr><td>Component index</td><td>The index of the component in the research object's data model, or the component ID</td></tr><tr><td>Component suffix</td><td><a href="https://github.com/json-path/JsonPath">JSONPath</a> to manifest component. Encoded with slashes and compact format for URL friendliness.</td></tr></tbody></table>

**Example dPID Links for Data Access**

<table><thead><tr><th width="184">Type</th><th>Link</th></tr></thead><tbody><tr><td>Web</td><td><a href="https://beta.dpid.org/46">https://beta.dpid.org/46</a></td></tr><tr><td>Metadata</td><td><a href="https://beta.dpid.org/46?jsonld">https://beta.dpid.org/46?jsonld</a> and <a href="https://beta.dpid.org/46?raw">https://beta.dpid.org/46?raw</a></td></tr><tr><td>Past Metadata</td><td><a href="https://beta.dpid.org/46?raw">https://beta.dpid.org/46/v1?raw</a></td></tr><tr><td>Code</td><td><a href="https://beta.dpid.org/46/3/root/exploring-lupus/casa/J15430131-3409153_cont.py?raw">https://beta.dpid.org/46/3/root/exploring-lupus/casa/J15430131-3409153_cont.py?raw</a></td></tr><tr><td>Data</td><td><a href="https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt?raw">https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt?raw</a></td></tr></tbody></table>

**Note:** Excluding `?raw` results in resolving the human-accessible data in the Nodes App or another configured resolver application.

**API for Research Objects**

<table><thead><tr><th>Route</th><th>Behavior</th></tr></thead><tbody><tr><td>GET https://beta.dpid.org/api/v1/dpid</td><td><p>List all registered research objects</p><p></p><p>Query Params</p><p><code>page: number = 1 // first page</code></p><p><code>size: number = 100 // 100 items</code></p><p><code>sort: "asc" | "desc" = "desc" // sort descending</code></p><h4>Response</h4><pre class="language-json" data-overflow="wrap"><code class="lang-json">{
    "dpid": "54",
    "id": "0x0...",
    "recentCid": "bafkre...",
    "researchObject": {
        "id": "0x0...",
        "versions": [
            {
                "id": "0x0...",
                "time": 1685098464,
                "cid": "bafkre...",
            },
            {
                "id": "0x0...",
                "time": 1685098776,
                "cid": "bafkre...",
            }
        ]
    }
}
</code></pre></td></tr><tr><td>GET https://beta.dpid.org/46/v1?raw</td><td>Get metadata for specific version of specific research object (application format)<br><br>Response Typescript specification: <a href="https://github.com/desci-labs/nodes/blob/develop/desci-models/src/ResearchObject.ts">https://github.com/desci-labs/nodes/blob/develop/desci-models/src/ResearchObject.ts</a></td></tr><tr><td>GET https://beta.dpid.org/46/v1?jsonld</td><td>Get metadata for specific version of specific research object (semantic format)<br><br>Returns in <a href="https://www.researchobject.org/ro-crate/1.1/">RO-Crate 1.1 format</a><br><br>Response Typescript specification: <br><a href="https://github.com/desci-labs/nodes/blob/develop/desci-models/src/RoCrate.ts">https://github.com/desci-labs/nodes/blob/develop/desci-models/src/RoCrate.ts</a></td></tr></tbody></table>

**Navigating Data via dPID API**

| Route                                                                                                                                                                                                                                                                                                                   | Behavior                                                                                                                                                                                                      |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <p>GET <a href="https://beta.dpid.org/46/root?raw"><https://beta.dpid.org/46/root?raw></a><br>GET <a href="https://beta.dpid.org/46/v1/root?raw"><https://beta.dpid.org/46/v1/root?raw></a><br><br><code>deprecated</code><br>GET <https://beta.dpid.org/46/data?raw><br>GET <https://beta.dpid.org/46/v1/data?raw></p> | These all do the same thing. Get the [DAG-JSON](https://ipld.io/docs/codecs/known/dag-json/) encoded content of the root data folder. If version specified, uses that version, otherwise uses latest version. |
| GET <https://beta.dpid.org/46/root/exploring-lupus-report.pdf?raw>                                                                                                                                                                                                                                                      | Download the specific file specified, if not a file, but a folder, the DAG-JSON encoded content is shown                                                                                                      |

**Valid PID syntax and variants**

There are three different and valid variants of the PIDs that can be resolved over HTTP. These variants offer different levels of friendliness for humans.&#x20;

<table><thead><tr><th width="107.33333333333331">Variant types</th><th width="318">Variant syntax (human)</th><th>Variant syntax (machine)</th></tr></thead><tbody><tr><td>Short form URL variant <br>(<strong>recommended</strong>)</td><td><a href="https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt">https://beta.dpid.org/46/v4/root/exploring-lupus/output/data_lup.txt</a></td><td><a href="https://beta.dpid.org/46/v4/data/exploring-lupus/output/data_lup.txt?raw">https://beta.dpid.org/46/v4/data/exploring-lupus/output/data_lup.txt?raw</a></td></tr><tr><td>Short form URL variant 0-index<span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span><br><code>deprecated</code></td><td><a href="https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt"><em><mark style="color:blue;">https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt</mark></em></a></td><td><a href="https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt?raw">https://beta.dpid.org/46/3/data/exploring-lupus/output/data_lup.txt?raw</a></td></tr><tr><td>Long form URL <span data-gb-custom-inline data-tag="emoji" data-code="26a0">⚠️</span> <strong>coming soon</strong></td><td><em><mark style="color:blue;">dpid.org/42/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/1/measurements.csv</mark></em></td><td><em><mark style="color:blue;">dpid.org/42/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/1/measurements.csv?raw</mark></em></td></tr></tbody></table>