summaryrefslogtreecommitdiff
path: root/docs/dev/openapi.yml
blob: 0c928e2d08d4627ec83f7afb002a09df9c7b32b8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
openapi: 3.0.1

info:
  title: HedgeDoc
  description: HedgeDoc is an open source collaborative note editor. Several tasks of HedgeDoc can be automated through this API.
  version: 1.7.0-rc2
  contact:
    name: HedgeDoc on GitHub
    url: https://github.com/hedgedoc/hedgedoc
  license:
    name: AGPLv3
    url: https://github.com/hedgedoc/hedgedoc/blob/master/LICENSE

externalDocs:
  url: https://github.com/hedgedoc/hedgedoc/blob/master/docs/dev/api.md


paths:

  /new:
    get:
      tags:
        - note
      summary: Creates a new note.
      description: A random id will be assigned and the content will equal to the template (blank by default). After note creation a redirect is issued to the created note.
      responses:
        default:
          description: Redirect to the new note
    post:
      tags:
        - note
      summary: Imports some markdown data into a new note.
      description: A random id will be assigned and the content will equal to the body of the received HTTP-request.
      requestBody:
        required: true
        description: The content of the note to be imported as markdown
        content:
          'text/markdown':
            example: '# Some header'
      responses:
        default:
          description: Redirect to the imported note

  /new/{alias}:
    post:
      tags:
        - note
      summary: Imports some markdown data into a new note with a given alias.
      description: 'This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](../configuration-env-vars.md#users-and-privileges) is enabled.'
      requestBody:
        required: true
        description: The content of the note to be imported as markdown
        content:
          'text/markdown':
            example: '# Some heading'
      responses:
        default:
          description: Redirect to the imported note
      parameters:
        -
          name: alias
          in: path
          required: true
          description: The alias for the note-id under which the note will be saved
          content:
            'text/plain':
              example: my-note

  /{note}/download:
    get:
      tags:
        - note
      summary: Returns the raw markdown content of a note.
      responses:
        200:
          description: The raw markdown content of the note
          content:
            'text/markdown':
              example: '# Some heading'
        404:
          description: Note does not exist
      parameters:
        -
          name: note
          in: path
          required: true
          description: The note which should be downloaded
          content:
            'text/plain':
              example: my-note

  /{note}/publish:
    get:
      tags:
        - note
      summary: Redirects to the published version of the note.
      responses:
        default:
          description: Redirect to the published version of the note
        404:
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note which should be published
          content:
            'text/plain':
              example: my-note

  /{note}/slide:
    get:
      tags:
        - note
      summary: Redirects to the slide-presentation of the note.
      description: This is only useful on notes which are designed to be slides.
      responses:
        default:
          description: Redirect to the slide version of the note
        404:
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note which should be shown as slide
          content:
            'text/plain':
              example: my-note

  /{note}/info:
    get:
      tags:
        - note
      summary: Returns metadata about the note.
      description: This includes the title and description of the note as well as the creation date and viewcount.
      responses:
        200:
          description: Metadata about the note
          content:
            'text/json':
              schema:
                type: object
                properties:
                  title:
                    type: string
                    description: The title of the note
                    default: Untitled
                  description:
                    type: string
                    description: The description of the note or the first words from the note
                  viewcount:
                    type: integer
                    minimum: 0
                    description: How often the published version of the note was viewed
                  createtime:
                    type: string
                    description: The timestamp when the note was created in ISO 8601 format.
                  updatetime:
                    type: string
                    description: The timestamp when the note was last updated in ISO 8601 format.
        404:
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the info should be shown
          content:
            'text/plain':
              example: my-note

  /{note}/revision:
    get:
      tags:
        - note
      summary: Returns a list of the available note revisions.
      description: The list is returned as a JSON object with an array of revision-id and length associations. The revision-id equals to the timestamp when the revision was saved.
      responses:
        200:
          description: Revisions of the note
          content:
            'text/json':
              schema:
                type: object
                properties:
                  revision:
                    type: array
                    description: Array that holds all revision-info objects
                    items:
                      type: object
                      properties:
                        time:
                          type: integer
                          description: UNIX-timestamp of when the revision was saved. Is also the revision-id.
                        length:
                          type: integer
                          description: Length of the document to the timepoint the revision was saved
        404:
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which revisions should be shown
          content:
            'text/plain':
              example: my-note

  /{note}/revision/{revision-id}:
    get:
      tags:
        - note
      summary: Returns the revision of the note with some metadata.
      description: The revision is returned as a JSON object with the content of the note and the authorship.
      responses:
        200:
          description: Revision of the note for the given timestamp
          content:
            'text/json':
              schema:
                type: object
                properties:
                  content:
                    type: string
                    description: The raw markdown content of the note revision
                  authorship:
                    type: array
                    description: Data which gives insights about who worked on the note
                    items:
                      type: integer
                      description: Unique user ids and additional data
                  patch:
                    type: array
                    description: Data which gives insight about what changed in comparison to former revisions
                    items:
                      type: string
        404:
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the revision should be shown
          content:
            'text/plain':
              example: my-note
        - name: revision-id
          in: path
          required: true
          description: The id (timestamp) of the revision to fetch
          content:
            'text/plain':
              example: 1570921051959

  /{note}/gist:
    get:
      tags:
        - note
      summary: Creates a new GitHub Gist with the note's content.
      description: 'If [GitHub integration](https://github.com/hedgedoc/hedgedoc/blob/master/docs/configuration-env-vars.md#github-login) is configured, the user will be redirected to GitHub and a new Gist with the content of the note will be created.'
      responses:
        default:
          description: Redirect to the created gist (or the GitHub authentication before)
        404:
          description: Note does not exist
      parameters:
        - name: note
          in: path
          required: true
          description: The note which should be pasted to GitHub gist
          content:
            'text/plain':
              example: my-note

  /me:
    get:
      tags:
        - user
      summary: Returns the profile data of the current logged-in user.
      description: The data is returned as a JSON object containing the user-id, the user's name and a url to the profile picture. Requires an active session of the user.
      responses:
        200:
          description: If the user is logged-in, the user data otherwise `{"status":"forbidden"}`
          content:
            'text/json':
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: ok if everything works as expected, forbidden is the user is not logged-in
                  id:
                    type: string
                    description: Unique id of the user
                  name:
                    type: string
                    description: The user's display name
                  photo:
                    type: string
                    description: An url to the online stored user profile photo

  /me/export:
    get:
      tags:
        - user
      summary: Exports a zip-archive with all notes of the current user.
      responses:
        default:
          description: The zip-archive with all notes

  /history:
    get:
      tags:
        - user
      summary: Returns a list of the last viewed notes.
      description: The list is returned as a JSON object with an array containing for each entry it's id, title, tags, last visit time and pinned status.
      responses:
        200:
          description: The list of recently viewed notes and pinned notes
          content:
            'text/json':
              schema:
                type: object
                properties:
                  history:
                    type: array
                    description: The array that contains history objects
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The id or alias of the note
                        text:
                          type: string
                          description: The title of the note
                        time:
                          type: integer
                          description: The UNIX-timestamp when the note was last accessed by the user
                        tags:
                          type: array
                          description: The tags that were added by the user to the note
                          items:
                            type: string
                        pinned:
                          type: boolean
                          description: Whether the user has pinned this note
    post:
      tags:
        - user
      summary: Replace user's history with a new one.
      description: The body must be form-encoded and contain a field `history` with a JSON-encoded array like its returned from the server when exporting the history.
      requestBody:
        required: true
        content:
          'application/x-www-form-urlencoded':
            example: 'history=[{"id":"example","text":"Untitled","time":1556275442010,"tags":[],"pinned":false}]'
      responses:
        200:
          description: History replaced
    delete:
      tags:
        - user
      summary: Deletes the user's history.
      responses:
        200:
          description: User's history deleted

  /history/{note}:
    post:
      tags:
        - user
      summary: Toggles the pinned status in the history for a note.
      description: The body must be form-encoded and contain a field `pinned` that is either `true` or `false`.
      requestBody:
        required: true
        content:
          'application/x-www-form-urlencoded':
            example: 'pinned=false'
      responses:
        200:
          description: Pinned state toggled
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the pinned state should be toggled
          content:
            'text/plain':
              example: my-note
    delete:
      tags:
        - user
      summary: Deletes a note from the user's history.
      responses:
        200:
          description: Pinned state toggled
      parameters:
        - name: note
          in: path
          required: true
          description: The note for which the pinned state should be toggled
          content:
            'text/plain':
              example: my-note

  /status:
    get:
      tags:
        - server
      summary: Returns the current status of the HedgeDoc instance.
      description: The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more.
      responses:
        200:
          description: The server info
          content:
            'text/json':
              schema:
                type: object
                properties:
                  onlineNotes:
                    type: integer
                    description: How many notes are edited at the moment
                  onlineUsers:
                    type: integer
                    description: How many users are online at the moment
                  distinctOnlineUsers:
                    type: integer
                    description: How many distinct users (different machines) are online at the moment
                  notesCount:
                    type: integer
                    description: How many notes are stored on the server
                  registeredUsers:
                    type: integer
                    description: How many users are registered on the server
                  onlineRegisteredUsers:
                    type: integer
                    description: How many of the online users are registered on the server
                  distinctOnlineRegisteredUsers:
                    type: integer
                    description: How many of the distinct online users are registered on the server
                  isConnectionBusy:
                    type: boolean
                  connectionSocketQueueLength:
                    type: integer
                  isDisconnectBusy:
                    type: boolean
                  disconnectSocketQueueLength:
                    type: integer

tags:
  - name: note
    description: These endpoints create notes, return information about them or export them.
  - name: user
    description: These endpoints return information about the current logged-in user and it's note history. If no user is logged-in, the most of this requests will fail with either a HTTP 403 or a JSON object containing `{"status":"forbidden"}`.
  - name: server
    description: These endpoints return information about the running HedgeDoc instance.