hedgedoc/docs/dev/public_api.yml

770 lines
24 KiB
YAML
Raw Normal View History

2020-05-24 15:00:16 -04:00
openapi: 3.0.3
info:
title: HedgeDoc
description: HedgeDoc is an open source collaborative note editor. Several tasks of HedgeDoc can be automated through this API.
2020-05-24 15:00:16 -04:00
version: 2.0.0
contact:
name: HedgeDoc on GitHub
url: https://github.com/codimd/server
license:
name: AGPLv3
url: https://github.com/codimd/server/blob/master/LICENSE
externalDocs:
description: The CodiMD Documentation.
2020-05-24 15:00:16 -04:00
url: https://github.com/codimd/server/tree/master/docs
servers:
- url: "/api/v2"
description: The base API Path.
security:
- bearerAuth: []
paths:
2020-05-24 15:00:16 -04:00
/me:
get:
tags:
- user
summary: Get the user information of the currently logged-in user
2020-05-24 15:00:16 -04:00
operationId: getMe
responses:
'200':
description: The user information.
2020-05-24 15:00:16 -04:00
content:
application/json:
schema:
"$ref": "#/components/schemas/UserInfo"
'401':
"$ref": "#/components/responses/UnauthorizedError"
/me/history:
2020-05-24 15:00:16 -04:00
get:
tags:
- history
- user
summary: Returns a list of the last viewed notes
operationId: getHistory
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:
application/json:
schema:
"$ref": "#/components/schemas/History"
'401':
"$ref": "#/components/responses/UnauthorizedError"
/me/history/{note}:
get:
tags:
- history
- user
summary: Returns History data for a note
operationId: getHistoryObject
description: JSON Object which contains id, title, tags, last visit time and pinned status
responses:
'200':
description: The list of recently viewed notes and pinned notes.
content:
application/json:
schema:
"$ref": "#/components/schemas/HistoryObject"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The name of the note which is used to address it.
content:
text/plain:
example: my-note
put:
tags:
- history
- user
summary: Update the history object of the note (e.g change it's pin status)
operationId: updateHistoryObject
requestBody:
description: The updated history object.
content:
application/json:
schema:
"$ref": "#/components/schemas/HistoryObject"
responses:
'200':
description: The new history.
content:
application/json:
schema:
"$ref": "#/components/schemas/HistoryObject"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which the revision should be shown.
content:
text/plain:
example: my-note
delete:
tags:
- history
- user
summary: Remove the note from the currently logged-in user's history
operationId: deleteHistoryObject
responses:
'204':
"$ref": "#/components/responses/SuccessfullyDeleted"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which the revision should be shown.
content:
text/plain:
example: my-note
/me/notes:
get:
tags:
- user
summary: Returns a list of the notes metadata the user owns
operationId: getOwnNotes
description: The list is returned as a JSON object with an array containing each notes metadata.
responses:
'200':
description: The list of notes owned by the currently logged in user.
content:
application/json:
schema:
type: array
description: The array that contains notes metadata.
items:
"$ref": "#/components/schemas/NoteMetadata"
'401':
"$ref": "#/components/responses/UnauthorizedError"
/notes:
post:
tags:
- note
summary: Imports some markdown data into a new note
2020-05-24 15:00:16 -04:00
operationId: createNoteFromMarkdown
description: A random id will be assigned and the content will equal to the body of the received HTTP-request.
security:
- bearerAuth: []
- {}
requestBody:
2020-05-27 05:30:32 -04:00
required: false
description: The content of the note to be imported as markdown.
content:
'text/markdown':
2020-05-24 15:00:16 -04:00
schema:
type: string
examples:
markdownExample:
"$ref": '#/components/examples/markdownExample'
responses:
'200':
description: Get information about the newly created note.
2020-05-24 15:00:16 -04:00
content:
application/json:
schema:
2020-05-27 07:25:37 -04:00
"$ref": "#/components/schemas/Note"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
/notes/{note}:
2020-05-27 05:30:32 -04:00
get:
tags:
- note
summary: Returns the note
2020-05-27 05:30:32 -04:00
operationId: getNote
description: This includes all metadata and the content of the note.
responses:
'200':
description: All data of the note.
2020-05-27 05:30:32 -04:00
content:
application/json:
schema:
"$ref": "#/components/schemas/Note"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
2020-05-27 05:30:32 -04:00
parameters:
- name: note
in: path
required: true
description: The name of the note which is used to address it.
2020-05-27 05:30:32 -04:00
content:
text/plain:
example: my-note
post:
tags:
- note
summary: Imports some markdown data into a new note with a given alias
2020-05-24 15:00:16 -04:00
operationId: createNoteWithAlias
description: This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/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':
2020-05-24 15:00:16 -04:00
schema:
type: string
examples:
markdownExample:
"$ref": '#/components/examples/markdownExample'
responses:
'200':
description: Get information about the newly created note.
2020-05-24 15:00:16 -04:00
content:
application/json:
schema:
2020-05-27 07:25:37 -04:00
"$ref": "#/components/schemas/Note"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'409':
description: This alias is already in use.
parameters:
- name: note
in: path
required: true
description: The name of the note which is used to address it.
content:
text/plain:
example: my-note
delete:
tags:
- note
summary: Remove the note
operationId: deleteNote
responses:
'204':
"$ref": "#/components/responses/SuccessfullyDeleted"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which the revision should be shown.
content:
text/plain:
example: my-note
put:
tags:
- note
summary: Imports some markdown data into an existing note, creating a new revision
operationId: createNewRevisionForNote
description: This endpoint equals to the above one except that the alias from the url will be assigned to the note if [FreeURL-mode](https://github.com/codimd/server/tree/master/docs/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':
schema:
type: string
examples:
markdownExample:
"$ref": '#/components/examples/markdownExample'
responses:
'200':
description: The new, changed note
content:
2020-05-27 05:30:32 -04:00
application/json:
2020-05-24 15:00:16 -04:00
schema:
"$ref": "#/components/schemas/Note"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which the info should be shown.
content:
2020-05-24 15:00:16 -04:00
text/plain:
example: my-note
/notes/{note}/metadata:
put:
tags:
- note
summary: Set the permissions of a note
operationId: updateNoteMetadata
requestBody:
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/NoteMetadata"
responses:
'200':
description: The updated permissions of the note.
content:
2020-05-27 05:30:32 -04:00
application/json:
schema:
"$ref": "#/components/schemas/NoteMetadata"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which the info should be shown.
content:
text/plain:
example: my-note
get:
tags:
- note
summary: Get the permissions of a note
operationId: getNoteMetadata
responses:
'200':
description: The permissions of the note.
content:
application/json:
schema:
"$ref": "#/components/schemas/NoteMetadata"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which the info should be shown.
content:
2020-05-24 15:00:16 -04:00
text/plain:
example: my-note
/notes/{note}/revisions:
get:
tags:
- note
summary: Returns a list of the available note revisions
2020-05-24 15:00:16 -04:00
operationId: getAllRevisionsOfNote
description: The list contains the revision-id, the length and a ISO-timestamp of the creation date.
responses:
'200':
description: Revisions of the note.
content:
2020-05-24 15:00:16 -04:00
application/json:
schema:
2020-05-24 15:00:16 -04:00
"$ref": "#/components/schemas/NoteRevisionsMetadata"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which revisions should be shown.
content:
2020-05-24 15:00:16 -04:00
text/plain:
example: my-note
/notes/{note}/revisions/{revision-id}:
get:
tags:
- note
summary: Returns the revision of the note with some metadata
2020-05-24 15:00:16 -04:00
operationId: getSpecificRevisionOfNote
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 id.
content:
2020-05-24 15:00:16 -04:00
application/json:
schema:
2020-05-24 15:00:16 -04:00
"$ref": "#/components/schemas/NoteRevision"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which the revision should be shown.
content:
2020-05-24 15:00:16 -04:00
text/plain:
example: my-note
- name: revision-id
in: path
required: true
description: The id of the revision to fetch.
content:
2020-05-24 15:00:16 -04:00
text/plain:
example: 1570921051959
/notes/{note}/content:
get:
tags:
- note
- export
summary: Returns the raw markdown content of a note
operationId: getNoteContent
responses:
'200':
description: The raw markdown content of the note.
content:
'text/markdown':
schema:
type: string
format: binary
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
parameters:
- name: note
in: path
required: true
description: The note for which the markdown should be exported.
content:
text/plain:
example: my-note
/media/upload:
post:
tags:
- media
summary: Uploads an image to the backend storage
description: Uploads an image to be processed by the backend.
requestBody:
required: true
description: The binary image to upload.
content:
image/*:
schema:
type: string
format: binary
responses:
'200':
description: The image was uploaded successfully.
content:
application/json:
schema:
type: object
properties:
link:
type: string
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
/monitoring:
2020-05-27 08:58:49 -04:00
get:
tags:
- monitoring
summary: Returns the current status of the backend
operationId: getMonitoring
description: The data is returned as a JSON object containing the number of notes stored on the server, (distinct) online users and more.
2020-05-27 08:58:49 -04:00
responses:
'200':
description: The server info.
2020-05-27 08:58:49 -04:00
content:
application/json:
schema:
"$ref": "#/components/schemas/ServerStatus"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
/monitoring/prometheus:
get:
tags:
- monitoring
summary: Returns the current status of the backend for Prometheus.
operationId: getPrometheus
description: The data is returned in Prometheus Exposition Format
responses:
'200':
description: Prometheus compatible monitoring data.
content:
text/plain: {}
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
2020-05-24 15:00:16 -04:00
components:
schemas:
UserInfo:
type: object
properties:
userName:
2020-05-24 15:00:16 -04:00
type: string
displayName:
2020-05-24 15:00:16 -04:00
type: string
photo:
type: string
format: uri
email:
type: string
format: email
UserPasswordChange:
type: object
properties:
password:
type: string
ImageProxyRequest:
type: object
properties:
src:
type: string
description: The url of the image that should be processed by the image proxy.
ImageProxyResponse:
type: object
properties:
src:
type: string
description: The url of the provied version of the image.
Note:
type: object
properties:
content:
type: string
description: The markdown content of the note
metadata:
$ref: "#/components/schemas/NoteMetadata"
editedByAtPosition:
type: array
description: Data which gives insights about who worked where on the note.
items:
type: integer
description: Unique user ids and additional data
NoteMetadata:
type: object
properties:
id:
type: string
format: UUIDv4
description: The id of the note.
alias:
type: string
description: The alias of the note.
title:
type: string
description: Title of the note
description:
type: string
description: Description of the note.
tags:
type: array
description: A list of tags attached to the note.
items:
type: string
description: A tag
updateTime:
type: string
description: ISO-timestamp of when the note was last changed.
updateUser:
$ref: "#/components/schemas/UserInfo"
viewCount:
2020-05-27 05:30:32 -04:00
type: integer
minimum: 0
description: How often the published version of the note was viewed.
createTime:
2020-05-27 05:30:32 -04:00
type: string
description: The ISO-timestamp when the note was created in ISO 8601 format.
editedBy:
type: array
description: List of usernames who edited the note.
items:
type: string
permissions:
$ref: "#/components/schemas/NotePermissions"
NotePermissions:
type: object
properties:
owner:
type: string
description: Username of the owner of the note
sharedTo:
type: array
description: Contains all usernames that can read the note and a boolean that denotes if they can also edit.
items:
type: object
properties:
username:
type: string
canEdit:
type: boolean
2020-05-24 15:00:16 -04:00
NoteRevisionsMetadata:
type: array
items:
type: object
properties:
id:
type: integer
description: The id of the revision
createdTime:
type: string
description: ISO-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.
2020-05-24 15:00:16 -04:00
NoteRevision:
type: object
properties:
content:
2020-05-24 15:00:16 -04:00
type: string
description: The raw markdown content of the note revision.
2020-05-24 15:00:16 -04:00
authorship:
type: array
description: Data which gives insights about who worked on the note.
2020-05-24 15:00:16 -04:00
items:
type: integer
description: Unique user ids and additional data.
2020-05-24 15:00:16 -04:00
patch:
type: array
description: Data which gives insight about what changed in comparison to former revisions.
2020-05-24 15:00:16 -04:00
items:
type: string
2020-05-27 05:30:32 -04:00
GistLink:
2020-05-24 15:00:16 -04:00
type: object
properties:
2020-05-27 05:30:32 -04:00
link:
2020-05-24 15:00:16 -04:00
type: string
2020-05-27 05:30:32 -04:00
format: uri
description: A Gist link.
2020-05-27 05:30:32 -04:00
DropboxLink:
type: object
properties:
link:
2020-05-24 15:00:16 -04:00
type: string
2020-05-27 05:30:32 -04:00
format: uri
description: A Dropbox link.
2020-05-24 15:00:16 -04:00
EmailLogin:
type: object
properties:
email:
type: string
format: email
password:
type: string
format: password
2020-05-27 05:30:32 -04:00
LdapLogin:
type: object
properties:
username:
type: string
format: email
password:
type: string
format: password
OpenIdLogin:
type: object
properties:
openId:
type: string
2020-05-24 15:00:16 -04:00
ServerStatus:
type: object
properties:
serverVersion:
type: object
properties:
major:
type: integer
minor:
type: integer
patch:
type: integer
preRelease:
type: string
commit:
type: string
description: Version of the server specified according to SemVer specification
2020-05-24 15:00:16 -04:00
onlineNotes:
type: integer
description: How many notes are edited at the moment.
2020-05-24 15:00:16 -04:00
onlineUsers:
type: integer
description: How many users are online at the moment.
2020-05-24 15:00:16 -04:00
distinctOnlineUsers:
type: integer
description: How many distinct users (different machines) are online at the moment.
2020-05-24 15:00:16 -04:00
notesCount:
type: integer
description: How many notes are stored on the server.
2020-05-24 15:00:16 -04:00
registeredUsers:
type: integer
description: How many users are registered on the server.
2020-05-24 15:00:16 -04:00
onlineRegisteredUsers:
type: integer
description: How many of the online users are registered on the server.
2020-05-24 15:00:16 -04:00
distinctOnlineRegisteredUsers:
type: integer
description: How many of the distinct online users are registered on the server.
2020-05-24 15:00:16 -04:00
isConnectionBusy:
type: boolean
connectionSocketQueueLength:
type: integer
isDisconnectBusy:
type: boolean
disconnectSocketQueueLength:
type: integer
2020-05-27 08:34:25 -04:00
HistoryObject:
type: object
properties:
metadata:
$ref: "#/components/schemas/NoteMetadata"
2020-05-27 08:34:25 -04:00
pinned:
type: boolean
description: Whether the user has pinned this note.
2020-05-27 08:34:25 -04:00
History:
type: object
properties:
history:
type: array
description: The array that contains history objects.
2020-05-27 08:34:25 -04:00
items:
"$ref": "#/components/schemas/HistoryObject"
2020-05-24 15:00:16 -04:00
examples:
markdownExample:
value: '# Some header\nSome normal text. **Some bold text**'
summary: A sample markdown content
securitySchemes:
bearerAuth:
type: http
scheme: bearer
responses:
UnauthorizedError:
description: Authorization information is missing or invalid.
ForbiddenError:
description: Access to the requested resource is not permitted.
NotFoundError:
description: The requested resource was not found.
SuccessfullyDeleted:
description: The requested resource was sucessfully deleted.