mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2025-05-12 22:26:08 -04:00
fc8f5dbbf5
With the suggested usage of an Authorization header instead of relying on session-cookies, the API will finally become stateless. Therefore we don't need the tokens for user password change and deletion anymore. Signed-off-by: Erik Michelson <github@erik.michelson.eu>
862 lines
25 KiB
YAML
862 lines
25 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: CodiMD
|
|
description: CodiMD is an open source collaborative note editor. Several tasks of CodiMD can be automated through this API.
|
|
version: 2.0.0
|
|
contact:
|
|
name: CodiMD on GitHub
|
|
url: https://github.com/codimd/server
|
|
license:
|
|
name: AGPLv3
|
|
url: https://github.com/codimd/server/blob/master/LICENSE
|
|
externalDocs:
|
|
description: CodiMD Documentation
|
|
url: https://github.com/codimd/server/tree/master/docs
|
|
servers:
|
|
- url: "/api/v2.0/"
|
|
description: "Base API Path"
|
|
paths:
|
|
/auth/email:
|
|
post:
|
|
tags:
|
|
- auth
|
|
summary: Trying to login via email
|
|
operationId: loginEmail
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EmailLogin'
|
|
responses:
|
|
'200':
|
|
description: login succesful
|
|
headers:
|
|
Set-Cookie:
|
|
schema:
|
|
type: string
|
|
/auth/ldap:
|
|
post:
|
|
tags:
|
|
- auth
|
|
summary: Trying to login via LDAP
|
|
operationId: loginLdap
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LdapLogin'
|
|
responses:
|
|
'200':
|
|
description: login succesful
|
|
headers:
|
|
Set-Cookie:
|
|
schema:
|
|
type: string
|
|
/auth/openid:
|
|
post:
|
|
tags:
|
|
- auth
|
|
summary: Trying to login via OpenID
|
|
operationId: loginOpenId
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/OpenIdLogin'
|
|
responses:
|
|
'200':
|
|
description: login succesful
|
|
headers:
|
|
Set-Cookie:
|
|
schema:
|
|
type: string
|
|
/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':
|
|
description: the user is not logged in
|
|
content: {}
|
|
post:
|
|
tags:
|
|
- user
|
|
summary: Update information about the currently logged-in user
|
|
operationId: updateMe
|
|
responses:
|
|
'200':
|
|
description: The user information was changed successfully
|
|
requestBody:
|
|
required: true
|
|
description: The new user information
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/UserUpdate"
|
|
delete:
|
|
tags:
|
|
- user
|
|
summary: "Deletes the currently logged-in user from the system and removes all it's notes"
|
|
operationId: deleteMe
|
|
responses:
|
|
'200':
|
|
description: The user was deleted successfully
|
|
/me/export:
|
|
get:
|
|
tags:
|
|
- user
|
|
summary: Exports a zip-archive with all notes of the current user.
|
|
responses:
|
|
'200':
|
|
description: The zip-archive with all notes
|
|
/me/password:
|
|
post:
|
|
tags:
|
|
- user
|
|
summary: Sets the new password of a user
|
|
requestBody:
|
|
required: true
|
|
description: The new password of the user
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/UserPasswordChange"
|
|
responses:
|
|
'200':
|
|
description: The password was changed
|
|
/status:
|
|
get:
|
|
tags:
|
|
- server
|
|
summary: Returns the current status of the CodiMD instance.
|
|
operationId: getStatus
|
|
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"
|
|
/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.
|
|
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:
|
|
'200':
|
|
description: Get information about the newly created note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Note"
|
|
/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"
|
|
'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
|
|
post:
|
|
tags:
|
|
- note
|
|
summary: Imports some markdown data into a new note with a given alias.
|
|
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':
|
|
schema:
|
|
type: string
|
|
examples:
|
|
markdownExample:
|
|
"$ref": '#/components/examples/markdownExample'
|
|
responses:
|
|
'200':
|
|
description: Get information about the newly created note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Note"
|
|
'409':
|
|
description: This alias is already in use
|
|
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}/permissions:
|
|
put:
|
|
tags:
|
|
- note
|
|
summary: Set the permissions of a note
|
|
operationId: updateNotePermissions
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NotePermissions"
|
|
responses:
|
|
'200':
|
|
description: The updated permissions of the note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NotePermissions"
|
|
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: getNotePermissions
|
|
responses:
|
|
'200':
|
|
description: The permissions of the note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NotePermissions"
|
|
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}/websocket:
|
|
get:
|
|
tags:
|
|
- note
|
|
summary: Returns the websocket of a note.
|
|
operationId: getNoteWebsocket
|
|
responses:
|
|
'200':
|
|
description: The websocket of the note
|
|
content: {}
|
|
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}/export/markdown:
|
|
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
|
|
'404':
|
|
description: Note does not exist
|
|
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}/export/html:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Returns the content of a note as HTML.
|
|
operationId: getNoteContentAsHTML
|
|
responses:
|
|
'200':
|
|
description: The raw html content of the note
|
|
content:
|
|
'text/html':
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'404':
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the html should be exported
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/notes/{note}/export/gist:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Exports the content of a note to a gist.
|
|
operationId: exportNoteToGist
|
|
responses:
|
|
'200':
|
|
description: The link to Gist of the note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": '#/components/schemas/GistLink'
|
|
'404':
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note which should be exported to gist
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/notes/{note}/export/dropbox:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Exports the content of a note to dropbox.
|
|
operationId: exportNoteToDropbox
|
|
responses:
|
|
'200':
|
|
description: The dropbox link of the note
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": '#/components/schemas/DropboxLink'
|
|
'404':
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note which should be exported to dropbox
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/notes/{note}/export/pdf:
|
|
get:
|
|
tags:
|
|
- note
|
|
- export
|
|
summary: Exports the content of a note as PDF.
|
|
operationId: exportNoteToPDF
|
|
responses:
|
|
'200':
|
|
description: The note as an PDF
|
|
content:
|
|
application/pdf:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
'404':
|
|
description: Note does not exist
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note which should be exported to dropbox
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/notes/{note}/revision:
|
|
get:
|
|
tags:
|
|
- note
|
|
summary: Returns a list of the available note revisions.
|
|
operationId: getAllRevisionsOfNote
|
|
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:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteRevisionsMetadata"
|
|
'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
|
|
|
|
/notes/{note}/revision/{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 timestamp
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/NoteRevision"
|
|
'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
|
|
/history:
|
|
get:
|
|
tags:
|
|
- history
|
|
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"
|
|
post:
|
|
tags:
|
|
- history
|
|
summary: Sets the history if none is already set
|
|
operationId: updateHistory
|
|
requestBody:
|
|
description: The history to update
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/History"
|
|
responses:
|
|
'200':
|
|
description: The new history
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/History"
|
|
delete:
|
|
tags:
|
|
- history
|
|
summary: Clear the users history
|
|
operationId: deleteHistory
|
|
responses:
|
|
'200':
|
|
description: Deleted the history
|
|
content: {}
|
|
/history/{note}/:
|
|
put:
|
|
tags:
|
|
- history
|
|
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"
|
|
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
|
|
summary: remove the history object of the note
|
|
operationId: deleteHistoryObject
|
|
responses:
|
|
'200':
|
|
description: The new history
|
|
content: {}
|
|
parameters:
|
|
- name: note
|
|
in: path
|
|
required: true
|
|
description: The note for which the revision should be shown
|
|
content:
|
|
text/plain:
|
|
example: my-note
|
|
/config:
|
|
get:
|
|
tags:
|
|
- config
|
|
summary: The config of the backend
|
|
operationId: getConfig
|
|
responses:
|
|
'200':
|
|
description: The config
|
|
content:
|
|
application/json:
|
|
schema:
|
|
"$ref": "#/components/schemas/Config"
|
|
components:
|
|
schemas:
|
|
UserInfo:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: UUIDv4
|
|
name:
|
|
type: string
|
|
photo:
|
|
type: string
|
|
format: uri
|
|
provider:
|
|
type: string
|
|
enum: ['facebook', 'github', 'twitter', 'gitlab', 'dropbox', 'google', 'saml', 'oauth2', 'email', 'ldap', 'openid']
|
|
UserPasswordChange:
|
|
type: object
|
|
properties:
|
|
password:
|
|
type: string
|
|
UserUpdate:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: The new display name of the user
|
|
Config:
|
|
type: object
|
|
properties:
|
|
allowAnonymous:
|
|
type: boolean
|
|
description: Wether anonymous notes are allowed
|
|
authProviders:
|
|
type: object
|
|
properties:
|
|
facebook:
|
|
type: boolean
|
|
description: Wether Facebook login is possible
|
|
github:
|
|
type: boolean
|
|
description: Wether GitHub login is possible
|
|
twitter:
|
|
type: boolean
|
|
description: Wether Twitter login is possible
|
|
gitlab:
|
|
type: boolean
|
|
description: Wether Gitlab login is possible
|
|
dropbox:
|
|
type: boolean
|
|
description: Wether Dropbox login is possible
|
|
google:
|
|
type: boolean
|
|
description: Wether Google login is possible
|
|
saml:
|
|
type: boolean
|
|
description: Wether SAML login is possible
|
|
oauth2:
|
|
type: boolean
|
|
description: Wether OAuth2 login is possible
|
|
email:
|
|
type: boolean
|
|
description: Wether E-Mail login is possible
|
|
ldap:
|
|
type: boolean
|
|
description: Wether LDAP login is possible
|
|
openid:
|
|
type: boolean
|
|
description: Wether OpenID login is possible
|
|
customAuthNames:
|
|
type: object
|
|
properties:
|
|
ldap:
|
|
type: string
|
|
description: The custom name for the LDAP Login
|
|
example: "FooBar LDAP"
|
|
oauth2:
|
|
type: string
|
|
description: The custom name for the OAuth2 Login
|
|
example: "Olaf2"
|
|
saml:
|
|
type: string
|
|
description: The custom name for the SAML Login
|
|
example: "aufSAMLn.de"
|
|
specialLinks:
|
|
type: object
|
|
properties:
|
|
privacy:
|
|
type: string
|
|
format: uri
|
|
description: Link to the privacy notice
|
|
termsOfUse:
|
|
type: string
|
|
format: uri
|
|
description: Link to the terms of use
|
|
imprint:
|
|
type: string
|
|
format: uri
|
|
description: Link to the imprint
|
|
version:
|
|
type: object
|
|
properties:
|
|
version:
|
|
type: string
|
|
sourceCodeUrl:
|
|
type: string
|
|
format: uri
|
|
issueTrackerUrl:
|
|
type: string
|
|
format: uri
|
|
Note:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: UUIDv4
|
|
description: The id of the note
|
|
alias:
|
|
type: string
|
|
description: The alias of the note
|
|
lastChange:
|
|
type: object
|
|
properties:
|
|
userId:
|
|
type: string
|
|
format: UUIDv4
|
|
description: The id of the user that last changed the note
|
|
user:
|
|
type: string
|
|
description: The name of the user that last changed the note
|
|
timestamp:
|
|
type: integer
|
|
description: UNIX-timestamp of when the note was last changed.
|
|
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.
|
|
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
|
|
NotePermissions:
|
|
type: object
|
|
properties:
|
|
permission:
|
|
type: string
|
|
enum: ['freely', 'editable', 'limited', 'locked', 'protected', 'private']
|
|
NoteRevisionsMetadata:
|
|
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
|
|
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
|
|
OpenIdLogin:
|
|
type: object
|
|
properties:
|
|
openId:
|
|
type: string
|
|
ServerStatus:
|
|
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
|
|
HistoryObject:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The id or alias of the note
|
|
title:
|
|
type: string
|
|
description: The title of the note
|
|
lastVisited:
|
|
type: integer
|
|
description: The UNIX-timestamp in milliseconds 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
|
|
History:
|
|
type: object
|
|
properties:
|
|
history:
|
|
type: array
|
|
description: The array that contains history objects
|
|
items:
|
|
"$ref": "#/components/schemas/HistoryObject"
|
|
examples:
|
|
markdownExample:
|
|
value: '# Some header\nSome normal text. **Some bold text**'
|
|
summary: A sample markdown content
|