Skip to content

Define HTTP POST binding #196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 13, 2025
Merged

Define HTTP POST binding #196

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ce51796
Define HTTP POST binding in addition to HTTP GET
peacekeeper Sep 18, 2025
72eaf12
Apply suggestions from code review
peacekeeper Sep 24, 2025
389131e
Merge branch 'gh-pages' into peacekeeper-define-post-binding
peacekeeper Oct 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 51 additions & 22 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2221,16 +2221,8 @@ <h2>HTTP(S) Binding</h2>
<pre class="example nohighlight">https://resolver.example/1.0/identifiers/did:example:1234</pre></li>
<li>Set the <code>Accept</code> <var>HTTP request header</var> to `application/did-resolution"`
in order to request a complete <a href="#did-resolution-result"></a>, OR</li>
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>resolution option</var>.</li>
<li>If any other <var>resolution options</var> are provided:
<ol class="algorithm">
<li>The <var>input <a>DID</a></var> MUST be URL-encoded (as specified in <a
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
<li>Encode all <var>resolution options</var> except <b>accept</b> as
query parameters in the <var>request HTTP(S) URL</var>.
<pre class="example nohighlight">https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2</pre></li>
</ol>
</li>
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>resolution option</var>
in order to request only the <b>didDocument</b> value of the result.</li>
</ol>
</li>
<li>For the <a>DID URL dereferencing</a> function:
Expand All @@ -2239,20 +2231,57 @@ <h2>HTTP(S) Binding</h2>
<pre class="example nohighlight">https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf</pre></li>
<li>Set the <code>Accept</code> <var>HTTP request header</var> to `application/did-url-dereferencing"`
in order to request a complete <a href="#did-url-dereferencing-result"></a>, OR</li>
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>dereferencing option</var>.</li>
<li>If any other <var>dereferencing options</var> are provided:
<ol class="algorithm">
<li>The <var>input <a>DID URL</a></var> MUST be URL-encoded (as specified in <a
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
<li>Encode all <var>dereferencing options</var> except <b>accept</b> as
query parameters in the <var>request HTTP(S) URL</var>.
<pre class="example nohighlight">https://resolver.example/1.0/identifiers/did%3Aexample%3A1234%3Fservice%3Dfiles%26relativeRef%3D%2Fresume.pdf?option1=value1&option2=value2</pre></li>
</ol>
</li>
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>dereferencing option</var>
in order to request only the <b>contentStream</b> value of the result.</li>
</ol>
</li>
<li>Execute an HTTP <code>GET</code> request on the <var>request HTTP(S) URL</var>. This invokes the <a>DID resolution</a> or
<a>DID URL dereferencing</a> function at the remote <a>DID resolver</a>.</li>
<li>For the HTTP(S) GET binding:
<ol class="algorithm">
<li>If any other <var>resolution options</var> or <var>dereferencing options</var> than <b>accept</b> are provided:
<ol class="algorithm">
<li>The <var>input <a>DID</a></var> MUST be URL-encoded (as specified in <a
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
<li>Encode all <var>resolution options</var> except <b>accept</b> as
query parameters in the <var>request HTTP(S) URL</var>.
</ol>
</li>
<li>Execute an HTTP <code>GET</code> request on the <var>request HTTP(S) URL</var>. This invokes the <a>DID resolution</a> or
<a>DID URL dereferencing</a> function at the remote <a>DID resolver</a>.
<pre class="example nohighlight">GET https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2 HTTP/1.1
Accept: application/did-resolution
</pre>
<pre class="example nohighlight">GET https://resolver.example/1.0/identifiers/did%3Aexample%3A1234%3Fservice%3Dfiles%26relativeRef%3D%2Fresume.pdf?option1=value1&option2=value2 HTTP/1.1
Accept: application/did-url-dereferencing
</pre>
</li>
</ol>
</li>
<li>For the HTTP(S) POST binding:
<ol class="algorithm">
<li>If any other <var>resolution options</var> or <var>dereferencing options</var> than <b>accept</b> are provided:
<ol class="algorithm">
<li>Encode all <var>resolution options</var> except <b>accept</b> as
a JSON structure in the HTTP request's POST body.
</ol>
</li>
<li>Execute an HTTP <code>POST</code> request on the <var>request HTTP(S) URL</var>. This invokes the <a>DID resolution</a> or
<a>DID URL dereferencing</a> function at the remote <a>DID resolver</a>.
<pre class="example nohighlight">POST https://resolver.example/1.0/identifiers/did:example:1234 HTTP/1.1
Accept: application/did-resolution

{
"option1": "value1",
"option2": "value2"
}</pre>
<pre class="example nohighlight">POST https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf HTTP/1.1
Accept: application/did-url-dereferencing

{
"option1": "value1",
"option2": "value2"
}</pre>
</ol>
</li>
<li>If the <a>DID resolution</a> or <a>DID URL dereferencing</a> function returns an <b>error</b> metadata property in the
<b>didResolutionMetadata</b> or <b>dereferencingMetadata</b>,
then the HTTP response status code MUST correspond to the value of the <b>error</b> metadata property,
Expand Down
58 changes: 58 additions & 0 deletions openapi/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,64 @@ paths:
description: The options for resolving the DID or dereferencing the DID URL.
style: form
explode: true
post:
summary: Resolve a DID / Dereference a DID URL
description: <p>This endpoint either resolves a DID, or dereferences a DID URL.
When resolving a DID,
it takes the DID and resolution options as inputs, and
the output is a DID document plus metadata.
When dereferencing a DID URL,
it takes the DID URL and dereferencing options as inputs, and
the output is a DID document, a part of a DID document, or some
other resource identified by the DID URL.</p>
<p>See the <a href="<a href="https://www.w3.org/TR/did-resolution/">DID
Resolution</a> specification for additional details.</p>
operationId: resolve
tags:
- Universal Resolver
parameters:
- in: path
required: true
name: identifier
schema:
type: string
description: The DID to be resolved, or the DID URL to be dereferenced.
examples:
example1:
value: did:indy:sovrin:builder:VbPQNHsvoLZdaNU7fTBeFx
description: A DID using the `indy` method.
example2:
value: did:ion:EiClkZMDxPKqC9c-umQfTkR8vvZ9JPhl_xLDI9Nfk38w5w
description: A DID using the `ion` method.
example3:
value: did:ebsi:z25ZZFS7FweHsm9MX2Qvc6gc
description: A DID using the `ebsi` method.
- in: header
required: false
name: Accept
schema:
type: string
description: The requested media type of the DID document representation or
DID resolution result.
examples:
application/did:
value: application/did
description: Media type of a DID document.
application/did-resolution:
value: application/did-resolution
description: Media type of a DID resolution result.
application/did-url-dereferencing:
value: application/did-url-dereferencing
description: Media type of a DID URL dereferencing result.
requestBody:
content:
application/did-resolution:
schema:
$ref: "#/components/schemas/ResolutionOptions"
application/did-url-dereferencing:
schema:
$ref: "#/components/schemas/DereferencingOptions"
description: The options for resolving the DID or dereferencing the DID URL.
responses:
"200":
description: successfully resolved!
Expand Down
Loading