You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
53 lines
3.6 KiB
Markdown
53 lines
3.6 KiB
Markdown
5 years ago
|
# API Documentation
|
||
|
|
|
||
|
|
The NotePost API is extremely simple to use. Requests can be sent via GET or POST, and responses are sent in JSON.
|
||
|
|
|
||
|
|
## Request Structure
|
||
|
|
|
||
|
|
API URLs are typically of the form `http(s)://notepost-url/api/<action>/?args`.
|
||
|
|
|
||
|
|
Clients can authenticate to the API by using HTTP Basic Authentication or by including `username` and `password` arguments.
|
||
|
|
|
||
|
|
## Response Structure
|
||
|
|
|
||
|
|
Responses to well-formed requests will have a `status` field containing the string `OK` or `ERROR`.
|
||
|
|
If `status` is `ERROR`, there will also be a field named `msg` containing a human-readable localized error message suitable for display to the user.
|
||
|
|
If `status` is `OK`, there may or may not be additional fields sent, depending on the `action`.
|
||
|
|
|
||
|
|
If the request is not well-formed (missing required arguments, invalid credentials, or invalid action), the API will send a 4xx HTTP code and some plain text, such as `"400 Bad Request"`, `"403 Unauthorized"`, or `"404 Action not defined"`.
|
||
|
|
|
||
|
|
## Note JSON Format
|
||
|
|
```js
|
||
|
|
{
|
||
|
|
"noteid": 10,
|
||
|
|
"color": "673AB7",
|
||
|
|
"content": "#Note\ncontent",
|
||
|
|
"html": "<h1>Note</h1><p>content</p>",
|
||
|
|
"title": "Note",
|
||
|
|
"modified": "2018-12-28 17:24:58",
|
||
|
|
"favorite": false,
|
||
|
|
"owner": {
|
||
|
|
"uid": 1,
|
||
|
|
"username": "someone",
|
||
|
|
"name": "Some One"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Actions
|
||
|
|
|
||
|
|
| Action | Additional Arguments | Description
|
||
|
|
| ------------- | --------------------- | -----------
|
||
|
|
| `ping` | None | Used to check if the server is online and responding. Responds with `{"status":"OK"}`.
|
||
|
|
| `getnotes` | None | Returns all the notes that are readable with the sent credentials, as an array named `notes`. See note format above.
|
||
|
|
| `getnote` | `id` | Get one note by its ID.
|
||
|
|
| `savenote` | `text`, `id` (optional), `color` (optional), `modified` (optional), `favorite` (optional), `archived` (optional) | Update a note and return the updated note in `note`. <br>If `id` is not set, creates a new note. Returns the saved note as JSON, along with a `msg` containing a translated "Note saved" message. <br>If `color` is set to six hexadecimal digits, the note's background color will be set. <br>If `modified` is set to a string parsable by PHP `strtotime`, the note's last modified date will be set accordingly, otherwise the current date and time will be used. <br>If `favorite` is set to either `0` (no) or `1` (yes), the note's favorite/starred status will be updated. <br>`archived` is ignored for now, but will operate the same as `favorite` in the future as a non-destructive form of deletion.
|
||
|
|
| `deletenote` | `id` | Delete a note by its ID. This is not reversible.
|
||
|
|
| `favoritenote`| `id`, `favorite` (optional) | If `favorite` is not set, the favorite status of the note will be toggled. If `favorite` is set to either `0` (no) or `1` (yes), the note will be set as favorited or not.
|
||
|
|
| `tolist` | `id` | Convert a note to a list by prepending a checkbox (`- [ ]`) to each line of text. Returns the updated note as `note`.
|
||
|
|
| `togglelist` | `id`, `text` | Toggle the checked/crossed out state of the given line of text in the given note.
|
||
|
|
|
||
|
|
|
||
|
|
## Nextcloud Notes API
|
||
|
|
|
||
|
|
A subset of NotePost's functionality can also be accessed via a server implementation the [Nextcloud Notes API](https://github.com/nextcloud/notes/wiki/API-0.2). Use it via `https://notepost-url/lib/nextcloudnotes.php`, or if your webserver is configured correctly (see the .htaccess file in the NotePost root folder), at `https://notepost-url/index.php/apps/notes/api/v0.2`. See the linked Nextcloud documentation for usage information.
|