Fork of github.com/did-method-plc/did-method-plc
flesh out openapi3 schema
+340
-12
+340
-12
go-didplc/cmd/webplc/spec/plc-server-openapi3.yaml
+340
-12
go-didplc/cmd/webplc/spec/plc-server-openapi3.yaml
···
1
1
openapi: 3.0.0
2
2
info:
3
+
title: "did:plc Directory Server API"
3
4
version: 0.1
4
-
title: DID PLC Directory API
5
+
contact:
6
+
name: "Protocol Team at Bluesky"
7
+
email: "protocol@blueskyweb.xyz"
8
+
url: "https://web.plc.directory"
9
+
description: |
10
+
DID PLC is a self-authenticating [DID](https://www.w3.org/TR/did-core/) which is strongly-consistent, recoverable, and allows for key rotation.
11
+
12
+
The central directory server receives and persists self-signed operation logs for each DID, starting with a "genesis operation" which defined the DID identifier itself. This document describes the HTTP API for interacting with the directory server to resolve DID Document, fetch audit logs, and submit signed operations.
5
13
14
+
The HTTP API is permissionless, but only valid (correctly signed) operations are accepted. Reasonable rate-limits are applied, but they should not interfer with account recovery in most situations.
6
15
servers:
7
16
- url: https://plc.directory
8
17
9
18
paths:
10
19
/{did}:
11
20
get:
12
-
description: "Fetch DID Document"
21
+
description: "Resolve DID Document for the indicated DID"
22
+
operationId: ResolveDid
13
23
parameters:
14
24
- name: did
15
25
in: path
···
18
28
type: string
19
29
responses:
20
30
'200':
21
-
description: "Successfully returned DID Document"
31
+
description: "Success, returned DID Document"
22
32
content:
23
33
application/did+ld+json:
24
-
$ref: '#/components/schemas/DidDocument'
34
+
schema:
35
+
$ref: '#/components/schemas/DidDocument'
25
36
'404':
26
-
$ref: '#/components/responses/404NotFound'
37
+
$ref: '#/components/responses/404DidNotFound'
38
+
'410':
39
+
$ref: '#/components/responses/410DidNotAvailable'
40
+
x-codeSamples:
41
+
- lang: Shell
42
+
label: curl
43
+
source: |
44
+
curl -s https://plc.directory/did:plc:pyc2ihzpelxtg4cdkfzbhcv4 | jq .
45
+
- lang: Python
46
+
label: Python
47
+
source: |
48
+
import requests
49
+
50
+
did = "did:plc:pyc2ihzpelxtg4cdkfzbhcv4"
51
+
resp = requests.get(f"https://plc.directory/{did}")
52
+
resp.raise_for_status()
53
+
print(resp.json())
27
54
post:
28
-
/{did}/data:
29
-
get:
55
+
description: "Create new PLC Operation for the indicated DID"
56
+
operationId: CreatePlcOp
57
+
parameters:
58
+
- name: did
59
+
in: path
60
+
required: true
61
+
schema:
62
+
type: string
63
+
requestBody:
64
+
required: true
65
+
content:
66
+
application/json:
67
+
schema:
68
+
$ref: '#/components/schemas/Operation'
69
+
responses:
70
+
'200':
71
+
description: "Success, operation validated and persisted"
72
+
# TODO: what is returned here?
73
+
'400':
74
+
$ref: '#/components/responses/400BadOperation'
75
+
'404':
76
+
$ref: '#/components/responses/404DidNotFound'
77
+
'410':
78
+
$ref: '#/components/responses/410DidNotAvailable'
30
79
/{did}/log:
31
80
get:
81
+
description: "Get Current PLC Operation Chain"
82
+
operationId: GetPlcOpLog
83
+
parameters:
84
+
- name: did
85
+
in: path
86
+
required: true
87
+
schema:
88
+
type: string
89
+
responses:
90
+
'200':
91
+
description: "Success, retured operation log"
92
+
content:
93
+
application/json:
94
+
schema:
95
+
type: array
96
+
items:
97
+
$ref: '#/components/schemas/Operation'
98
+
'404':
99
+
$ref: '#/components/responses/404DidNotFound'
32
100
/{did}/log/audit:
33
101
get:
102
+
description: "Get PLC Operation Audit Log"
103
+
operationId: GetPlcAuditLog
104
+
parameters:
105
+
- name: did
106
+
in: path
107
+
required: true
108
+
schema:
109
+
type: string
110
+
responses:
111
+
'200':
112
+
description: "Success, retured audit log"
113
+
content:
114
+
application/json:
115
+
schema:
116
+
type: array
117
+
items:
118
+
$ref: '#/components/schemas/LogEntry'
119
+
'404':
120
+
$ref: '#/components/responses/404DidNotFound'
34
121
/{did}/log/last:
35
122
get:
123
+
description: "Get Latest PLC Operation"
124
+
operationId: GetLastOp
125
+
parameters:
126
+
- name: did
127
+
in: path
128
+
required: true
129
+
schema:
130
+
type: string
131
+
responses:
132
+
'200':
133
+
description: "Success, returned latest operation"
134
+
content:
135
+
application/json:
136
+
schema:
137
+
$ref: '#/components/schemas/LogEntry'
138
+
'404':
139
+
$ref: '#/components/responses/404DidNotFound'
140
+
/{did}/data:
141
+
get:
142
+
description: "Get Current PLC Data for the indicated DID"
143
+
operationId: GetPlcData
144
+
parameters:
145
+
- name: did
146
+
in: path
147
+
required: true
148
+
schema:
149
+
type: string
150
+
responses:
151
+
'200':
152
+
description: "Success, retured current PLC data"
153
+
# TODO: basically just an op, but missing some fields? sigh.
154
+
'404':
155
+
$ref: '#/components/responses/404DidNotFound'
156
+
'410':
157
+
$ref: '#/components/responses/410DidNotAvailable'
36
158
/export:
37
159
get:
160
+
description: "Bulk fetch PLC Operations for all DIDs, with pagination, in JSON Lines format"
161
+
operationId: Export
162
+
parameters:
163
+
- name: count
164
+
in: query
165
+
schema:
166
+
type: integer
167
+
default: 10
168
+
maximum: 1000
169
+
- name: after
170
+
in: query
171
+
schema:
172
+
type: string
173
+
format: date-time
174
+
description: "Return only operations after this indexed timestamp"
175
+
responses:
176
+
'200':
177
+
description: "Success, returned batch of operations"
178
+
content:
179
+
application/jsonlines:
180
+
description: "Newline-delimited JSON file, with a separate JSON object on each line"
181
+
schema:
182
+
$ref: '#/components/schemas/LogEntry'
183
+
'400':
184
+
$ref: '#/components/responses/400BadRequest'
38
185
39
186
components:
40
187
responses:
41
-
404NotFound:
42
-
description: "DID not found"
188
+
404DidNotFound:
189
+
description: "DID Not Found"
190
+
content:
191
+
application/json:
192
+
schema:
193
+
type: object
194
+
properties:
195
+
message:
196
+
type: string
197
+
example:
198
+
message: "DID not registered: did:plc:ewvi7nxzyoun6zhxrhs64oiz"
199
+
404DidNotAvailable:
200
+
description: "DID Not Available (Tombstone)"
43
201
content:
44
202
application/json:
45
203
schema:
···
47
205
properties:
48
206
message:
49
207
type: string
208
+
example:
209
+
message: "DID not available: did:plc:ewvi7nxzyoun6zhxrhs64oiz"
210
+
400BadOperation:
211
+
description: "Invalid PLC Operation"
212
+
content:
213
+
application/json:
214
+
schema:
215
+
type: object
216
+
properties:
217
+
message:
218
+
type: string
219
+
example:
220
+
message: "Invalid Signature"
221
+
400BadRequest:
222
+
description: "Bad Request"
223
+
content:
224
+
application/json:
225
+
schema:
226
+
type: object
227
+
properties:
228
+
message:
229
+
type: string
230
+
example:
231
+
message: "Invalid Query Parameter"
50
232
schemas:
51
233
Operation:
52
234
oneOf:
···
61
243
create: '#/components/schemas/LegacyCreateOp'
62
244
PlcOp:
63
245
type: object
246
+
description: "Regular PLC operation. Can be a genesis operation (create DID, no 'prev' field), or a data update."
64
247
required:
65
248
- type
66
249
- rotationKeys
···
76
259
type: array
77
260
items:
78
261
type: string
262
+
description: "Ordered set (no duplicates) of cryptographic public keys in did:key format"
79
263
verificationMethods:
80
264
type: object
265
+
description: "Map (object) of application-specific cryptographic public keys in did:key format"
81
266
alsoKnownAs:
82
267
type: array
83
268
items:
84
269
type: string
270
+
description: "Ordered set (no duplicates) of aliases and names for this account, in the form of URIs"
271
+
services:
272
+
type: object
273
+
description: "Map (object) of application-specific service endpoints for this account"
85
274
prev:
86
275
type: string
87
276
nullable: true
277
+
description: "Strong reference (hash) of preceeding operation for this DID, in string CID format. Null for genesis operation"
88
278
sig:
89
279
type: string
280
+
description: "Cryptographic signature of this object, with base64 string encoding"
281
+
example:
282
+
type: "plc_operation"
283
+
services:
284
+
atproto_pds:
285
+
type: "AtprotoPersonalDataServer"
286
+
endpoint: "https://bsky.social"
287
+
alsoKnownAs:
288
+
- "at://atproto.com"
289
+
rotationKeys:
290
+
- "did:key:zQ3shhCGUqDKjStzuDxPkTxN6ujddP4RkEKJJouJGRRkaLGbg"
291
+
- "did:key:zQ3shpKnbdPx3g3CmPf5cRVTPe1HtSwVn5ish3wSnDPQCbLJK"
292
+
verificationMethods:
293
+
atproto: "did:key:zQ3shXjHeiBuRCKmM36cuYnm7YEMzhGnCmCyW92sRJ9pribSF"
294
+
90
295
TombstoneOp:
296
+
type: object
297
+
description: "Special operation which deactives (revokes) the DID. This is permanent once the recovery window expires."
91
298
required:
92
299
- type
93
300
- prev
···
97
304
type: string
98
305
prev:
99
306
type: string
307
+
description: "Strong reference (hash) of preceeding operation for this DID, in string CID format"
100
308
sig:
101
309
type: string
310
+
description: "Cryptographic signature of this object, with base64 string encoding"
311
+
example:
312
+
type: "plc_tombstone"
313
+
prev: "bafyreid6awsb6lzc54zxaq2roijyvpbjp5d6mii2xyztn55yli7htyjgqy"
314
+
sig: "41iJmrPRUTIi24HBduzgoavjOibAx2yFJ2p1d7zTN6ZmMgjSaTF8dJf0HtdU4EBNUBTWq33PZyh5tyb1bJq3Fw"
315
+
102
316
LegacyCreateOp:
317
+
type: object
318
+
description: "Obsolete PLC genesis operations, which must still be supported to ensure all did:plc identifiers can be resolved correctly."
103
319
required:
104
320
- type
105
321
- signingKey
···
113
329
type: string
114
330
signingKey:
115
331
type: string
332
+
description: "atproto cryptographic public key in did:key format"
116
333
recoveryKey:
117
334
type: string
335
+
description: "PLC recovery cryptographic public key in did:key format"
118
336
handle:
119
337
type: string
338
+
description: "atproto handle as AT-URI (at://)"
120
339
service:
121
340
type: string
341
+
description: "atproto_pds service endpoint URL"
122
342
prev:
123
343
type: string
124
344
nullable: true
345
+
description: "Strong reference (hash) of preceeding operation for this DID, in string CID format"
125
346
sig:
126
347
type: string
348
+
description: "Cryptographic signature of this object, with base64 string encoding"
349
+
example:
350
+
type: "create"
351
+
signingKey: "did:key:zQ3shP5TBe1sQfSttXty15FAEHV1DZgcxRZNxvEWnPfLFwLxJ"
352
+
recoveryKey: "did:key:zQ3shhCGUqDKjStzuDxPkTxN6ujddP4RkEKJJouJGRRkaLGbg"
353
+
handle: "first-post.bsky.social"
354
+
service: "https://bsky.social"
355
+
prev: null
356
+
sig: "yvN4nQYWTZTDl9nKSSyC5EC3nsF5g4S56OmRg9G6_-pM6FCItV2U2u14riiMGyHiCD86l6O-1xC5MPwf8vVsRw"
127
357
128
-
errors:
129
-
400: Not a valid operation
130
-
404: DID not registered
358
+
LogEntry:
359
+
type: object
360
+
required:
361
+
- did
362
+
- operation
363
+
- cid
364
+
- nullified
365
+
- createdAt
366
+
properties:
367
+
did:
368
+
type: string
369
+
description: "DID that this operation applies to"
370
+
operation:
371
+
$ref: "#/components/schemas/Operation"
372
+
cid:
373
+
type: cid
374
+
description: "Hash of the operation, in string CID format"
375
+
nullified:
376
+
type: bool
377
+
description: "Whether this operation is included in the current operation chain, or has been overridden"
378
+
createdAt:
379
+
type: string
380
+
format: date-time
381
+
description: "Timestamp when this operation was received by the directory server"
382
+
example:
383
+
did: "did:plc:ewvi7nxzyoun6zhxrhs64oiz"
384
+
operation:
385
+
sig: "lza4at_jCtGo_TYgL5PC1ZNP7lhF4DV8H50LWHhvdHcB143x1wEwqZ43xvV36Pws6OOnJLJrkibEUFDFqkhIhg"
386
+
prev: null
387
+
type: "plc_operation"
388
+
services:
389
+
atproto_pds:
390
+
type: "AtprotoPersonalDataServer"
391
+
endpoint: "https://bsky.social"
392
+
alsoKnownAs:
393
+
- "at://atprotocol.bsky.social"
394
+
rotationKeys:
395
+
- "did:key:zQ3shhCGUqDKjStzuDxPkTxN6ujddP4RkEKJJouJGRRkaLGbg"
396
+
- "did:key:zQ3shpKnbdPx3g3CmPf5cRVTPe1HtSwVn5ish3wSnDPQCbLJK"
397
+
verificationMethods:
398
+
atproto: "did:key:zQ3shXjHeiBuRCKmM36cuYnm7YEMzhGnCmCyW92sRJ9pribSF"
399
+
cid: "bafyreibfvkh3n6odvdpwj54j4xxdsgnn4zo5utbyf7z7nfbyikhtygzjcq"
400
+
nullified: false
401
+
createdAt: "2023-04-26T06:19:25.508Z"
402
+
403
+
DidDocument:
404
+
type: object
405
+
required:
406
+
- id
407
+
properties:
408
+
id:
409
+
type: string
410
+
example: "did:plc:ewvi7nxzyoun6zhxrhs64oiz"
411
+
alsoKnownAs:
412
+
type: array
413
+
description: "Ordered set (no duplicates) of aliases and names for this account, in the form of URIs"
414
+
items:
415
+
type: string
416
+
example: "at://atproto.com"
417
+
verificationMethods:
418
+
type: array
419
+
items:
420
+
type: object
421
+
required:
422
+
- id
423
+
- type
424
+
- controller
425
+
- publicKeyMultibase
426
+
properties:
427
+
id:
428
+
type: string
429
+
type:
430
+
type: string
431
+
controller:
432
+
type: string
433
+
publicKeyMultibase:
434
+
type: string
435
+
example:
436
+
id: "#atproto"
437
+
type: "EcdsaSecp256k1VerificationKey2019"
438
+
controller: "did:plc:ewvi7nxzyoun6zhxrhs64oiz"
439
+
publicKeyMultibase: "zQYEBzXeuTM9UR3rfvNag6L3RNAs5pQZyYPsomTsgQhsxLdEgCrPTLgFna8yqCnxPpNT7DBk6Ym3dgPKNu86vt9GR"
440
+
service:
441
+
type: array
442
+
items:
443
+
type: object
444
+
required:
445
+
- id
446
+
- type
447
+
- serviceEndpoint
448
+
properties:
449
+
id:
450
+
type: string
451
+
type:
452
+
type: string
453
+
serviceEndpoint:
454
+
type: string
455
+
example:
456
+
id: "#atproto_pds"
457
+
type: "AtprotoPersonalDataServer"
458
+
serviceEndpoint: "https://bsky.social"