Skip to content

Commit 3ef6617

Browse files
peacekeeperTallTed
peacekeeper
and
TallTed
authored
Define HTTP POST binding (#196)
* Define HTTP POST binding in addition to HTTP GET * Apply suggestions from code review Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com> --------- Co-authored-by: Ted Thibodeau Jr <tthibodeau@openlinksw.com>
1 parent 8876f2b commit 3ef6617

File tree

2 files changed

+111
-24
lines changed

2 files changed

+111
-24
lines changed

‎index.html‎

Lines changed: 53 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -2315,39 +2315,68 @@ <h2>HTTP(S) Binding</h2>
23152315
<li>Append the <var>input <a>DID</a></var> to the <var>request HTTP(S) URL</var>.
23162316
<pre class="example nohighlight">https://resolver.example/1.0/identifiers/did:example:1234</pre></li>
23172317
<li>Set the <code>Accept</code> <var>HTTP request header</var> to `application/did-resolution`
2318-
in order to request a complete <a href="#did-resolution-result"></a>, OR</li>
2319-
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>resolution option</var>.</li>
2320-
<li>If any other <var>resolution options</var> are provided:
2321-
<ol class="algorithm">
2322-
<li>The <var>input <a>DID</a></var> MUST be URL-encoded (as specified in <a
2323-
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
2324-
<li>Encode all <var>resolution options</var> except <b>accept</b> as
2325-
query parameters in the <var>request HTTP(S) URL</var>.
2326-
<pre class="example nohighlight">https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2</pre></li>
2327-
</ol>
2328-
</li>
2318+
to request a complete <a href="#did-resolution-result"></a>, OR</li>
2319+
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>resolution option</var>
2320+
to request only the <b>didDocument</b> value of the result.</li>
23292321
</ol>
23302322
</li>
23312323
<li>For the <a>DID URL dereferencing</a> function:
23322324
<ol class="algorithm">
23332325
<li>Append the <var>input <a>DID URL</a></var> to the <var>request HTTP(S) URL</var>.
23342326
<pre class="example nohighlight">https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf</pre></li>
23352327
<li>Set the <code>Accept</code> <var>HTTP request header</var> to `application/did-url-dereferencing`
2336-
in order to request a complete <a href="#did-url-dereferencing-result"></a>, OR</li>
2337-
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>dereferencing option</var>.</li>
2338-
<li>If any other <var>dereferencing options</var> are provided:
2339-
<ol class="algorithm">
2340-
<li>The <var>input <a>DID URL</a></var> MUST be URL-encoded (as specified in <a
2341-
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
2342-
<li>Encode all <var>dereferencing options</var> except <b>accept</b> as
2343-
query parameters in the <var>request HTTP(S) URL</var>.
2344-
<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>
2345-
</ol>
2346-
</li>
2328+
to request a complete <a href="#did-url-dereferencing-result"></a>, OR</li>
2329+
<li>set the <code>Accept</code> <var>HTTP request header</var> to the value of the <b>accept</b> <var>dereferencing option</var>
2330+
to request only the <b>contentStream</b> value of the result.</li>
23472331
</ol>
23482332
</li>
2349-
<li>Execute an HTTP <code>GET</code> request on the <var>request HTTP(S) URL</var>. This invokes the <a>DID resolution</a> or
2350-
<a>DID URL dereferencing</a> function at the remote <a>DID resolver</a>.</li>
2333+
<li>For the HTTP(S) GET binding:
2334+
<ol class="algorithm">
2335+
<li>If any other <var>resolution options</var> or <var>dereferencing options</var> than <b>accept</b> are provided:
2336+
<ol class="algorithm">
2337+
<li>The <var>input <a>DID</a></var> MUST be URL-encoded (as specified in <a
2338+
data-cite="RFC3986#section-2.1">RFC3986 Section 2.1</a>).</li>
2339+
<li>Encode all <var>resolution options</var> except <b>accept</b> as
2340+
query parameters in the <var>request HTTP(S) URL</var>.
2341+
</ol>
2342+
</li>
2343+
<li>Execute an HTTP <code>GET</code> request on the <var>request HTTP(S) URL</var>. This invokes the <a>DID resolution</a> or
2344+
<a>DID URL dereferencing</a> function at the remote <a>DID resolver</a>.
2345+
<pre class="example nohighlight">GET https://resolver.example/1.0/identifiers/did%3Aexample%3A1234?option1=value1&option2=value2 HTTP/1.1
2346+
Accept: application/did-resolution
2347+
</pre>
2348+
<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
2349+
Accept: application/did-url-dereferencing
2350+
</pre>
2351+
</li>
2352+
</ol>
2353+
</li>
2354+
<li>For the HTTP(S) POST binding:
2355+
<ol class="algorithm">
2356+
<li>If any other <var>resolution options</var> or <var>dereferencing options</var> than <b>accept</b> are provided:
2357+
<ol class="algorithm">
2358+
<li>Encode all <var>resolution options</var> except <b>accept</b> as
2359+
a JSON structure in the HTTP request's POST body.
2360+
</ol>
2361+
</li>
2362+
<li>Execute an HTTP <code>POST</code> request on the <var>request HTTP(S) URL</var>. This invokes the <a>DID resolution</a> or
2363+
<a>DID URL dereferencing</a> function at the remote <a>DID resolver</a>.
2364+
<pre class="example nohighlight">POST https://resolver.example/1.0/identifiers/did:example:1234 HTTP/1.1
2365+
Accept: application/did-resolution
2366+
2367+
{
2368+
"option1": "value1",
2369+
"option2": "value2"
2370+
}</pre>
2371+
<pre class="example nohighlight">POST https://resolver.example/1.0/identifiers/did:example:1234?service=files&relativeRef=/resume.pdf HTTP/1.1
2372+
Accept: application/did-url-dereferencing
2373+
2374+
{
2375+
"option1": "value1",
2376+
"option2": "value2"
2377+
}</pre>
2378+
</ol>
2379+
</li>
23512380
<li>If the <a>DID resolution</a> or <a>DID URL dereferencing</a> function returns an <b>error</b> metadata property in the
23522381
<b>didResolutionMetadata</b> or <b>dereferencingMetadata</b>,
23532382
then the HTTP response status code MUST correspond to the value of the <b>error</b> metadata property,

‎openapi/openapi.yaml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,64 @@ paths:
6868
description: The options for resolving the DID or dereferencing the DID URL.
6969
style: form
7070
explode: true
71+
post:
72+
summary: Resolve a DID / Dereference a DID URL
73+
description: <p>This endpoint either resolves a DID, or dereferences a DID URL.
74+
When resolving a DID,
75+
it takes the DID and resolution options as inputs, and
76+
the output is a DID document plus metadata.
77+
When dereferencing a DID URL,
78+
it takes the DID URL and dereferencing options as inputs, and
79+
the output is a DID document, a part of a DID document, or some
80+
other resource identified by the DID URL.</p>
81+
<p>See the <a href="<a href="https://www.w3.org/TR/did-resolution/">DID
82+
Resolution</a> specification for additional details.</p>
83+
operationId: resolve
84+
tags:
85+
- Universal Resolver
86+
parameters:
87+
- in: path
88+
required: true
89+
name: identifier
90+
schema:
91+
type: string
92+
description: The DID to be resolved, or the DID URL to be dereferenced.
93+
examples:
94+
example1:
95+
value: did:indy:sovrin:builder:VbPQNHsvoLZdaNU7fTBeFx
96+
description: A DID using the `indy` method.
97+
example2:
98+
value: did:ion:EiClkZMDxPKqC9c-umQfTkR8vvZ9JPhl_xLDI9Nfk38w5w
99+
description: A DID using the `ion` method.
100+
example3:
101+
value: did:ebsi:z25ZZFS7FweHsm9MX2Qvc6gc
102+
description: A DID using the `ebsi` method.
103+
- in: header
104+
required: false
105+
name: Accept
106+
schema:
107+
type: string
108+
description: The requested media type of the DID document representation or
109+
DID resolution result.
110+
examples:
111+
application/did:
112+
value: application/did
113+
description: Media type of a DID document.
114+
application/did-resolution:
115+
value: application/did-resolution
116+
description: Media type of a DID resolution result.
117+
application/did-url-dereferencing:
118+
value: application/did-url-dereferencing
119+
description: Media type of a DID URL dereferencing result.
120+
requestBody:
121+
content:
122+
application/did-resolution:
123+
schema:
124+
$ref: "#/components/schemas/ResolutionOptions"
125+
application/did-url-dereferencing:
126+
schema:
127+
$ref: "#/components/schemas/DereferencingOptions"
128+
description: The options for resolving the DID or dereferencing the DID URL.
71129
responses:
72130
"200":
73131
description: successfully resolved!

0 commit comments

Comments
 (0)