Skip to content

(docs): sync api docs with code #2047

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
blizzz wants to merge 7 commits into
base: main
Choose a base branch
from
+112 −35
Open

(docs): sync api docs with code #2047

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2533137
docs(api): document attachment deletion and errors
blizzz Sep 24, 2026
0567a83
docs(api): update settings, capabilities and error codes
blizzz Sep 24, 2026
5f1bd0e
docs: fix admin defaults and CI badges in README
blizzz Sep 24, 2026
0eddd63
docs: correct entry points and editor modes in AGENTS.md
blizzz Sep 24, 2026
78c214f
docs(api): use example.com placeholder domain
blizzz Sep 25, 2026
fb88780
docs: fix typos
blizzz Oct 1, 2026
3ed373e
docs: fix wrong word
blizzz Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,16 +64,16 @@ There are no PHP unit tests. Three suites exist:
### Backend (`lib/`)
- Two parallel controller stacks share logic via `lib/Controller/Helper.php`:
- `NotesController` — internal endpoints for the Vue frontend (`/notes/...`)
- `NotesApiController` — the **public versioned REST API** (`/api/v0.2|v1/...`, attachments on v1.4) used by the Android/iOS and third-party clients. It is a stability contract documented in `docs/api/` — changes must stay backward compatible and be reflected there (and in `lib/AppInfo/Capabilities.php` for new API versions).
- `NotesApiController` — the **public versioned REST API** (`/api/v0.2|v1/...`; attachment routes and `GET settings` also accept `v1.4`) used by the Android/iOS and third-party clients. It is a stability contract documented in `docs/api/` — changes must stay backward compatible and be reflected there (new API versions go into `Application::$API_VERSIONS` in `lib/AppInfo/Application.php`, exposed via `Capabilities.php` and the `X-Notes-API-Versions` header).
- Routes are declared in `appinfo/routes.php`.
- `lib/Service/NotesService.php` is the core: resolves the notes folder, wraps files in `Note` objects (`Note`/`MetaNote` are file wrappers, not entities). `MetaService` maintains the DB metadata cache; `NoteUtil`/`TagService` handle file/tag plumbing. Errors are communicated via typed exceptions in `lib/Service/` which `Helper` maps to HTTP status codes.
- `ChunkCursor` + ETags implement chunked/pruned note listing for large collections (see `docs/api/README.md`).
- App wiring (event listeners, dashboard widget, search provider, reference provider) lives in `lib/AppInfo/Application.php`.

### Frontend (`src/`)
- Entry points: `main.js` (main app), `dashboard.js` (dashboard widget), `config.js` (admin settings) — one webpack bundle each.
- Entry points: `main.js` (main app) and `dashboard.js` (dashboard widget) — one webpack bundle each. `config.js` only holds polling/autosave intervals.
- State lives in three Pinia stores (`src/stores/app.js`, `notes.js`, `sync.js`), aggregated by `src/store.js`. `src/NotesService.js` contains the server-communication layer including the sync queue and conflict handling (`ConflictSolution.vue`); components dispatch through it rather than calling axios directly.
- Note editing has three modes: `EditorEasyMDE.vue` (rich md editing), `EditorMarkdownIt.vue` (preview), `EditorPlain.vue`.
- Note editing has three modes (`noteMode` setting): `rich` (`NoteRich.vue`, embeds the Text app's editor), `edit` (`NotePlain.vue` with `EditorEasyMDE.vue`) and `preview` (`NotePlain.vue` with `EditorMarkdownIt.vue`).

## Conventions

Expand Down
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Nextcloud will notify you about possible updates. Please have a look at [CHANGEL
Before reporting bugs:

* get the newest version of the Notes app
* please consider also installing the [latest development version](https://github.com/nextcloud/notes/archive/master.zip)
* please consider also installing the [latest development version](https://github.com/nextcloud/notes/archive/main.zip)
* [check if they have already been reported](https://github.com/nextcloud/notes/issues)


Expand All @@ -33,8 +33,8 @@ Before reporting bugs:

## :warning: Developer Info

[![Lint](https://github.com/nextcloud/notes/workflows/Lint/badge.svg?branch=master&event=push)](https://github.com/nextcloud/notes/actions?query=workflow%3ALint+event%3Apush+branch%3Amaster)
[![Test](https://github.com/nextcloud/notes/workflows/Test/badge.svg?branch=master&event=push)](https://github.com/nextcloud/notes/actions?query=workflow%3ATest+event%3Apush+branch%3Amaster)
[![Test](https://github.com/nextcloud/notes/actions/workflows/test.yml/badge.svg?branch=main&event=push)](https://github.com/nextcloud/notes/actions/workflows/test.yml?query=branch%3Amain+event%3Apush)
[![Node tests](https://github.com/nextcloud/notes/actions/workflows/node-test.yml/badge.svg?branch=main&event=push)](https://github.com/nextcloud/notes/actions/workflows/node-test.yml?query=branch%3Amain+event%3Apush)

### Building the app

Expand Down Expand Up @@ -62,6 +62,6 @@ occ config:app:set notes defaultFolder --value="Shared notes"

| Setting | Property name | Default | Other available option(s) |
|---------|---------------|---------|---------------------------|
| Display mode for notes | noteMode | edit | preview |
| File extension for new notes | fileSuffix | .txt | .md |
| Display mode for notes | noteMode | rich (if the Text app is enabled), otherwise edit | edit, preview |
| File extension for new notes | fileSuffix | .md | .txt |
| Folder to store your notes | defaultFolder | Notes | _Custom_ |
28 changes: 15 additions & 13 deletions docs/api/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,30 +30,30 @@ We distinguish major and minor versions:
- a major version comes with changes that are incompatible to the previous version and therefore would break old clients. Major versions come with a new base URL path.
- a minor version has changes that are realized compatible to the previous version. Old clients can still use the current API endpoint, but they need adoption in order to use new features.

### Compability between minor versions
### Compatibility between minor versions

Minor versions of the same major version use the same API endpoint (path). Therefore, they must be compatible.

In order to realize forward compatibility between minor versions, clients must follow some general rules regarding the API:

- when processing the JSON response, unknown fields must be ignored (e.g. if API version 1.0 does not define the note's attribute "tags", a client must ignore such an unkown field in order to be compatible with a possible future version (e.g. 1.4) which defines such a field)
- when processing the JSON response, unknown fields must be ignored (e.g. if API version 1.0 does not define the note's attribute "tags", a client must ignore such an unknown field in order to be compatible with a possible future version (e.g. 1.4) which defines such a field)
- when processing the HTTP response code, a client must be able to handle newly introduced error codes (e.g. if API 1.0 does not explicitly define response code 405, the client must handle it at least like 400; same with a 5xx code).

In order to realize backwards compatibility between minor versions, a client must follow the following rules:

- when sending a request which uses a feature that wasn't available from beginning of the used major version, the client has to cope with the situation that the server ignores parts of the request
- when processing the JSON response, the server may ommit fields that where not available from beginning of the used major version
- when processing the JSON response, the server may omit fields that were not available from beginning of the used major version

If a client requires a certain feature, it should check the list of supported API version from server (see *Capabilities*).


### Capabilites
### Capabilities

From Notes app version 3.3, supported API versions can be queried using the [Nextcloud Capabilities API](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-api-overview.html#capabilities-api).

A request like

curl -u user:password -X GET -H "OCS-APIRequest: true" -H "Accept: application/json" https://yournextcloud.com/ocs/v2.php/cloud/capabilities
curl -u user:password -X GET -H "OCS-APIRequest: true" -H "Accept: application/json" https://nextcloud.example.com/ocs/v2.php/cloud/capabilities

will return the following result (in this example, irrelevant attributes are omitted and formatting was introduced):

Expand All @@ -63,8 +63,9 @@ will return the following result (in this example, irrelevant attributes are omi
"data": {
"capabilities": {
"notes": {
"api_version": [ "0.2", "1.0" ],
"version": "3.6.0"
"api_version": [ "0.2", "1.3", "1.4" ],
"version": "6.1.0",
"notes_path": "Notes"
}
}
}
Expand All @@ -74,12 +75,13 @@ will return the following result (in this example, irrelevant attributes are omi

| Attribute | Type | Description | since app version |
|:--------------|:----------------|:------------|:------------------|
| `api_version` | list of strings | list of supported API version; for each supported major API version, the highest supported minor API version is listed, e.g. `[ "0.2", "1.1" ]` | Notes 3.3 |
| `version` | string | app version, e.g. `"3.6.0"` | Notes 3.6 |
| `api_version` | list of strings | list of supported API versions; for each supported major API version, at least the highest supported minor API version is listed, e.g. `[ "0.2", "1.3", "1.4" ]`. Clients should use the highest listed minor version per major version. | Notes 3.3 |
| `version` | string | app version, e.g. `"6.1.0"` | Notes 3.6 |
| `notes_path` | string or null | path of the user's notes folder, relative to the user folder, e.g. `"Notes"`; `null` if the request is not authenticated | Notes 4.12 |

From Notes app version 3.3, the list of supported API versions is also provided in every response from the Notes API.
From Notes app version 3.3, the list of supported API versions is also provided in the responses from the Notes API (except for the *Get attachment* endpoint).
For this, the HTTP header `X-Notes-API-Versions` is used.
It contains a coma-separated list of versions, e.g., `X-Notes-API-Versions: 0.2, 1.0`.
It contains a comma-separated list of versions, e.g., `X-Notes-API-Versions: 0.2, 1.3, 1.4`.

### Processing API version information
In order to be compatible to older Notes version, you may want to implement multiple API versions in your client application.
Expand All @@ -97,9 +99,9 @@ Therefore running Nextcloud **with SSL is highly recommended** otherwise **every

You can test your request using `curl`:

curl -u user:password -H "Accept: application/json" https://yournextcloud.com/index.php/apps/notes/api/v1/notes
curl -u user:password -H "Accept: application/json" https://nextcloud.example.com/index.php/apps/notes/api/v1/notes

If you have enabled two-factor authentication you will have to create an app specific password for accessing the API. Please see [Nextcloud documentation](https://docs.nextcloud.com/server/latest/user_manual/session_management.html) for further details.
If you have enabled two-factor authentication you will have to create an app specific password for accessing the API. Please see [Nextcloud documentation](https://docs.nextcloud.com/server/latest/user_manual/en/session_management.html) for further details.

## Input parameters

Expand Down
Loading
Loading