Tutorial: Dereference DID URLs with the Vidos Resolver
In this tutorial, you'll learn how to dereference DID URLs using the Vidos Universal Resolver. By the end, you'll be able to retrieve resources associated with Decentralized Identifiers through a step-by-step process.
Prerequisites
Before you begin, make sure you have:
- A Vidos Resolver instance set up and running
- Your instance ID (we'll use
{YOUR_INSTANCE_ID}
as a placeholder)
- Basic understanding of Decentralized Identifiers (DIDs)
curl
or another HTTP client to make API requests
What you'll learn
In this tutorial, you'll:
- Understand the difference between DID Resolution and DID URL Dereferencing
- Construct valid DID URLs for dereferencing
- Make API calls to dereference DID URLs
- Interpret the dereferenced resources
- Handle common errors and troubleshoot issues
Step 1: Understand DID resolution vs. dereferencing
Before we start dereferencing, it's important to understand the distinction between DID resolution and DID dereferencing.
DID Resolution
DID resolution retrieves a complete DID document for a given DID. It's like looking up an entry in a directory to get all the information about an identity.
For example, resolving did:example:123
returns the entire DID document with all verification methods, services, and other properties.
DID Dereferencing
DID dereferencing takes things a step further. It allows you to retrieve a specific resource associated with a DID by using a DID URL with additional components like paths, queries, or fragments.
For example:
did:example:123#key-1
dereferences to retrieve just the verification method with ID key-1
did:example:123/resources/document
dereferences to retrieve a specific document resource
Step 2: Construct a DID URL for dereferencing
Let's construct a DID URL that we can dereference. For this tutorial, we'll use an example DID URL from the cheqd network:
did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0?resourceType=String&resourceMetadata=true
Let's break down this DID URL:
did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0
- The base DID
?resourceType=String&resourceMetadata=true
- Query parameters specifying we want:
- Resources of type "String"
- Include resource metadata in the response
TIP
You can construct different DID URLs depending on what you want to retrieve. If you want to access a specific verification method, you would use a fragment like #key-1
. If you want to access a service endpoint, you might use a path like /services/messaging
.
Step 3: Set up your dereferencing request
To dereference a DID URL, you'll make an HTTP GET request to your Vidos Resolver instance. The base URL format is:
https://{YOUR_INSTANCE_ID}.resolver.service.eu.vidos.id/{DID-URL}
Let's prepare our full request. We'll use the Accept
header to specify that we want the response in JSON-LD format:
::: code-group
curl -X GET \
'https://{YOUR_INSTANCE_ID}.resolver.service.eu.vidos.id/did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0?resourceType=String&resourceMetadata=true' \
-H 'Accept: application/ld+json'
const fetchResource = async () => {
const response = await fetch(
'https://{YOUR_INSTANCE_ID}.resolver.service.eu.vidos.id/did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0?resourceType=String&resourceMetadata=true',
{
headers: {
Accept: 'application/ld+json',
},
},
);
const data = await response.json();
console.log(data);
};
fetchResource();
:::
WARNING
When dereferencing a DID URL with a fragment, the fragment must be URL encoded. For example, #key-1
should be encoded as %23key-1
.
Step 4: Execute the dereferencing request
Now, execute the request you prepared in the previous step. Replace {YOUR_INSTANCE_ID}
with your actual Vidos Resolver instance ID.
If successful, you'll receive a response that includes the dereferenced resource. Here's an example of what the response might look like:
{
"contentStream": {
"created": "2023-01-25T11:58:10Z",
"versionId": "e5615fc2-6f13-42b1-989c-49576a574cef",
"linkedResourceMetadata": [
{
"resourceURI": "did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0/resources/9ba3922e-d5f5-4f53-b265-fc0d4e988c77",
"resourceCollectionId": "c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0",
"resourceId": "9ba3922e-d5f5-4f53-b265-fc0d4e988c77",
"resourceName": "Demo Resource",
"resourceType": "String",
"mediaType": "application/json",
"resourceVersion": "",
"created": "2023-01-25T12:08:39Z",
"checksum": "e1dbc03b50bdb995961dc8843df6539b79d03bf49787ed6462189ee97d27eaf3",
"previousVersionId": null,
"nextVersionId": null
},
{
"resourceURI": "did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0/resources/e733ebb7-c8dd-41ed-9d42-33bceea70952",
"resourceCollectionId": "c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0",
"resourceId": "e733ebb7-c8dd-41ed-9d42-33bceea70952",
"resourceName": "ResourceName",
"resourceType": "String",
"mediaType": "text/plain; charset=utf-8",
"resourceVersion": "",
"created": "2023-01-25T12:04:52Z",
"checksum": "cffd829b06797f85407be9353056db722ca3eca0c05ab0462a42d30f19cdef09",
"previousVersionId": null,
"nextVersionId": null
}
]
},
"dereferencingMetadata": {
"contentType": "application/did+ld+json",
"retrieved": "2024-06-13T13:09:23Z",
"did": {
"didString": "did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0",
"methodSpecificId": "c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0",
"method": "cheqd"
}
},
"contentMetadata": {}
}
Step 5: Understand the response
Let's break down the response:
-
contentStream: Contains the actual dereferenced content
- In this case, it includes a list of linked resources with metadata
- Each resource has properties like URI, name, type, and checksum
-
dereferencingMetadata: Information about the dereferencing process
contentType
: The format of the content
retrieved
: When the dereferencing happened
did
: Information about the base DID that was dereferenced
-
contentMetadata: Additional metadata about the content (empty in this example)
Step 6: Try different dereferencing options
Now that you understand the basics, let's explore some variations:
Dereference a specific resource by ID
If you want to dereference a specific resource, you can use a path in your DID URL:
did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0/resources/9ba3922e-d5f5-4f53-b265-fc0d4e988c77
::: code-group
bash [curl]
curl -X GET \ "https://{YOUR_INSTANCE_ID}
.resolver.service.eu.vidos.id/did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0/resources/9ba3922e-d5f5-4f53-b265-fc0d4e988c77"
\ -H 'Accept: application/ld+json'
:::
Request different content formats
You can request different content formats by changing the Accept
header:
::: code-group
# Request JSON format
curl -X GET \
"https://{YOUR_INSTANCE_ID}.resolver.service.eu.vidos.id/did:cheqd:testnet:c1685ca0-1f5b-439c-8eb8-5c0e85ab7cd0?resourceType=String" \ -H
'Accept: application/json'
:::
Step 7: Handle errors and troubleshoot
When working with DID dereferencing, you might encounter various errors. Here are some common issues and how to resolve them:
Invalid DID URL format
Error: 400 Bad Request
{
"error": "Invalid DID URL format"
}
Solution: Check your DID URL syntax. Ensure you've properly URL-encoded any special characters, especially fragments.
DID not found
Error: 404 Not Found
{
"error": "DID not found"
}
Solution: Verify that the DID exists and is correctly registered in the corresponding verifiable data registry.
Resource not found
Error: 404 Not Found
{
"error": "Resource not found"
}
Solution: Confirm that the resource identifier in your DID URL (path, fragment, or query) correctly references an existing resource.
Authorization error
Error: 401 Unauthorized
{
"error": "Unauthorized access"
}
Solution: Check that your resolver instance has the necessary permissions to access the requested resource.
Success criteria
You've successfully completed this tutorial if you can:
- ✅ Explain the difference between DID resolution and DID dereferencing
- ✅ Construct valid DID URLs for different dereferencing purposes
- ✅ Make API calls to dereference DIDs and retrieve resources
- ✅ Interpret the different parts of the dereferencing response
- ✅ Troubleshoot common dereferencing errors
Next steps
Now that you've learned how to dereference DID URLs with the Vidos Resolver, you can:
- Integrate DID dereferencing into your applications
- Explore more complex dereferencing patterns
- Learn about other Vidos services like the Authorizer or Verifier
- Dive deeper into DID methods and their specific dereferencing behaviors