hedgedoc/docs/content/dev/public_api.yml
Tilman Vatteroth 57bfca7b15 fix(frontend): refactor api error handling
Signed-off-by: Tilman Vatteroth <git@tilmanvatteroth.de>
2023-02-12 22:10:31 +01:00

933 lines
28 KiB
YAML

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.
version: 2.0.0
contact:
name: HedgeDoc on GitHub
url: https://github.com/hedgedoc/hedgedoc
license:
name: AGPLv3
url: https://github.com/hedgedoc/hedgedoc/blob/develop/LICENSE
externalDocs:
description: The HedgeDoc Documentation.
url: https://docs.hedgedoc.org
servers:
- url: "/api/v2"
description: The base API Path.
security:
- bearerAuth: []
paths:
/me:
get:
tags:
- user
summary: Get the user information of the currently logged-in user
operationId: getMe
responses:
'200':
description: The user information.
content:
application/json:
schema:
"$ref": "#/components/schemas/UserInfo"
'401':
"$ref": "#/components/responses/UnauthorizedError"
/me/history:
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:
type: array
items:
"$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: Information about the history entry
content:
application/json:
schema:
"$ref": "#/components/schemas/History"
'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/HistoryUpdate"
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"
/me/media:
get:
tags: [ user, media ]
summary: Get list of uploaded files owned by the current user
operationId: getOwnMedia
responses:
'200':
description:
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/MediaUpload"
/notes:
post:
tags:
- note
summary: Imports some markdown data into a new note
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:
required: false
description: The content of the note to be imported as markdown.
content:
'text/markdown':
schema:
type: string
examples:
markdownExample:
"$ref": '#/components/examples/markdownExample'
responses:
'201':
description: Get information about the newly created note.
content:
application/json:
schema:
"$ref": "#/components/schemas/Note"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
/notes/{note}:
get:
tags:
- note
summary: Returns the note
operationId: getNote
description: This includes all metadata and the content of the note.
responses:
'200':
description: All data of the note.
content:
application/json:
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 name of the note which is used to address it.
content:
text/plain:
example: my-note
post:
tags:
- note
summary: Imports some markdown data into a new note with a given alias
operationId: createNoteWithAlias
description: This endpoint creates a new note with the content of the HTTP request body and the alias from the URL parameter.
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:
'201':
description: Get information about the newly created note.
content:
application/json:
schema:
"$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 updates the note content of an existing note. The old content is completely replaced and a new revision is created.
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:
application/json:
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:
text/plain:
example: my-note
/notes/{note}/metadata:
get:
tags:
- note
summary: Get the metadata of a note
operationId: getNoteMetadata
responses:
'200':
description: The metadata 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:
text/plain:
example: my-note
/notes/{note}/metadata/permissions:
put:
tags: [ note ]
summary: Set permissions of a note
operationId: updateNotePermissions
requestBody:
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/NotePermissionsUpdate"
responses:
'200':
description: The updated permissions of the note.
content:
application/json:
schema:
"$ref": "#/components/schemas/NotePermissions"
'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
/notes/{note}/revisions:
get:
tags:
- note
summary: Returns a list of the available note revisions
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:
application/json:
schema:
type: array
items:
"$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:
text/plain:
example: my-note
/notes/{note}/revisions/{revision-id}:
get:
tags:
- note
summary: Returns the revision of the note with some metadata
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:
application/json:
schema:
"$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:
text/plain:
example: my-note
- name: revision-id
in: path
required: true
description: The id of the revision to fetch.
content:
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
/notes/{note}/media:
get:
tags: [ note, media ]
summary: Get list of files uploaded to the note
operationId: getOwnMedia
responses:
'200':
description:
content:
application/json:
schema:
type: array
items:
"$ref": "#/components/schemas/MediaUpload"
/media:
post:
tags:
- media
summary: Uploads a media file to the backend storage
description: Uploads a file to be processed by the backend.
requestBody:
required: true
description: The binary file to upload.
content:
image/apng:
schema:
type: string
format: binary
image/bmp:
schema:
type: string
format: binary
image/gif:
schema:
type: string
format: binary
image/heif:
schema:
type: string
format: binary
image/heic:
schema:
type: string
format: binary
image/heif-sequence:
schema:
type: string
format: binary
image/heic-sequence:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/svg+xml:
schema:
type: string
format: binary
image/tiff:
schema:
type: string
format: binary
image/webp:
schema:
type: string
format: binary
parameters:
- in: header
name: HedgeDoc-Note
schema:
type: string
required: true
description: ID or alias of the parent note
responses:
'201':
description: The file was uploaded successfully.
content:
application/json:
schema:
type: object
properties:
link:
type: string
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
/media/{filename}:
delete:
tags:
- media
summary: Delete the specified file
operationId: deleteMedia
parameters:
- name: filename
in: path
required: true
description: The name of the file to be deleted.
content:
text/plain:
example: e18d1b83e1821128615bad849ad0655a.jpg
responses:
'204':
"$ref": "#/components/responses/SuccessfullyDeleted"
'401':
"$ref": "#/components/responses/UnauthorizedError"
'403':
"$ref": "#/components/responses/ForbiddenError"
'404':
"$ref": "#/components/responses/NotFoundError"
/monitoring:
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.
responses:
'200':
description: The server info.
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"
components:
schemas:
UserInfo:
type: object
properties:
userName:
type: string
displayName:
type: string
photo:
type: string
format: uri
email:
type: string
format: email
UserPasswordChange:
type: object
properties:
password:
type: string
GroupInfo:
type: object
properties:
name:
type: string
displayName:
type: string
special:
type: boolean
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:
type: integer
minimum: 0
description: How often the published version of the note was viewed.
createTime:
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:
$ref: "#/components/schemas/UserInfo"
sharedToUsers:
type: array
description: Contains all users that can read the note and a boolean that denotes if they can also edit.
items:
type: object
properties:
user:
$ref: "#/components/schemas/UserInfo"
canEdit:
type: boolean
sharedToGroups:
type: array
description: Contains all groups that can read the note and a boolean that denotes if they can also edit.
items:
type: object
properties:
group:
$ref: "#/components/schemas/GroupInfo"
canEdit:
type: boolean
NotePermissionsUpdate:
type: object
description: Contains only title, description and tags of a note.
properties:
sharedToUsers:
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
sharedToGroups:
type: array
description: Contains all groups that can read the note and a boolean that denotes if they can also edit.
items:
type: object
properties:
groupname:
type: string
canEdit:
type: boolean
NoteRevisionsMetadata:
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.
NoteRevision:
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
GistLink:
type: object
properties:
link:
type: string
format: uri
description: A Gist link.
DropboxLink:
type: object
properties:
link:
type: string
format: uri
description: A Dropbox link.
EmailLogin:
type: object
properties:
email:
type: string
format: email
password:
type: string
format: password
LdapLogin:
type: object
properties:
username:
type: string
format: email
password:
type: string
format: password
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
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
History:
type: object
properties:
metadata:
$ref: "#/components/schemas/NoteMetadata"
pinned:
type: boolean
description: Whether the user has pinned this note.
HistoryUpdate:
type: object
properties:
pinned:
type: boolean
description: Whether the user has pinned this note.
History:
type: object
properties:
history:
type: array
description: The array that contains history objects.
items:
"$ref": "#/components/schemas/HistoryObject"
MediaUpload:
type: object
properties:
url:
type: string
description: URL of the file
owningNote:
type: string
description: ID of the note the file was uploaded to
createdAt:
type: string
format: date-time
description: Date when the file was upladed
owningUser:
type: string
description: username of the user who uploaded the file
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.