API documentation for API v1

README.md

@@ -1,7 +1,7 @@
 # Notes
 
 <!-- The following paragraph should be kept synchronized with the description in appinfo/info.xml -->
-The Notes app is a distraction free notes taking app for [Nextcloud](https://www.nextcloud.com/). It provides categories for better organization and supports formatting using [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax. Notes are saved as files in your Nextcloud, so you can view and edit them with every Nextcloud client. Furthermore, a separate [RESTful API](https://github.com/nextcloud/notes/wiki/API-0.2) allows for an easy integration into third-party apps (currently, there are notes apps for [Android](https://github.com/stefan-niedermann/nextcloud-notes), [iOS](https://github.com/owncloud/notes-iOS-App) and the [console](https://git.danielmoch.com/nncli/about) which allow convenient access to your Nextcloud notes). Further features include marking notes as favorites.
+The Notes app is a distraction free notes taking app for [Nextcloud](https://www.nextcloud.com/). It provides categories for better organization and supports formatting using [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax. Notes are saved as files in your Nextcloud, so you can view and edit them with every Nextcloud client. Furthermore, a separate [REST API](docs/api/README.md) allows for an easy integration into third-party apps (currently, there are notes apps for [Android](https://github.com/stefan-niedermann/nextcloud-notes), [iOS](https://github.com/owncloud/notes-iOS-App) and the [console](https://git.danielmoch.com/nncli/about) which allow convenient access to your Nextcloud notes). Further features include marking notes as favorites.
 
 ![Screenshot of Nextcloud Notes](https://raw.githubusercontent.com/nextcloud/screenshots/master/apps/Notes/notes.png)
 
@@ -29,8 +29,9 @@ 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)
 
-**Building the app**
+### Building the app
 
 1. Clone this into your `apps` folder of your Nextcloud
 2. In a terminal, run the command `make dev-setup` to install the dependencies
@@ -39,7 +40,6 @@ Before reporting bugs:
 4. Enable the app through the app management of your Nextcloud
 
 
-**Third-party apps**
+### REST API for third-party apps
-
-The notes app provides a JSON-API for third-party apps. You can find the documentation in [the wiki](https://github.com/nextcloud/notes/wiki).
 
+The notes app provides a JSON-API for third-party apps. Please have a look at our **[API documentation](docs/api/README.md)**.

appinfo/info.xml

@@ -5,7 +5,7 @@
     <name>Notes</name>
     <summary>Distraction-free notes and writing</summary>
     <description><![CDATA[
-The Notes app is a distraction free notes taking app. It provides categories for better organization and supports formatting using [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax. Notes are saved as files in your Nextcloud, so you can view and edit them with every Nextcloud client. Furthermore, a separate [RESTful API](https://github.com/nextcloud/notes/wiki/API-0.2) allows for an easy integration into third-party apps (currently, there are notes apps for [Android](https://github.com/stefan-niedermann/nextcloud-notes) and [iOS](https://github.com/owncloud/notes-iOS-App) which allow convenient access to your Nextcloud notes). Further features include marking notes as favorites.
+The Notes app is a distraction free notes taking app for [Nextcloud](https://www.nextcloud.com/). It provides categories for better organization and supports formatting using [Markdown](https://en.wikipedia.org/wiki/Markdown) syntax. Notes are saved as files in your Nextcloud, so you can view and edit them with every Nextcloud client. Furthermore, a separate [REST API](docs/api/README.md) allows for an easy integration into third-party apps (currently, there are notes apps for [Android](https://github.com/stefan-niedermann/nextcloud-notes), [iOS](https://github.com/owncloud/notes-iOS-App) and the [console](https://git.danielmoch.com/nncli/about) which allow convenient access to your Nextcloud notes). Further features include marking notes as favorites.
 ]]></description>
     <version>3.2.0</version>
     <licence>agpl</licence>

docs/api/README.md

@@ -0,0 +1,102 @@
+# API documentation
+
+The notes app comes with a REST-based API.
+It can be used in order to provide full access to notes from third-party apps.
+This documentation describes the API in detail.
+In this file, general information about the API is provided.
+The endpoint specification for a specific version can be found in separate files (see table below).
+
+
+## Major API versions
+
+| API version | Supported by app version | Documentation  |
+|:-----------:|:-------------------------|:--------|
+|  **1**      | since Notes 3.3 (May 2020)     | **[Documentation](v1.md)** |
+|  **0.2**    | since Notes 1.0 (2015)         | *(deprecated)* |
+
+
+## Versions and Capabilites
+
+While the notes app evolves and receives new features, it may be required to adopt the API.
+As far as possible, we try to make these changes backward compatible.
+However, this is not always possible.
+Therefore, a versioning scheme is realized in order to not break clients using an older API version.
+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.
+
+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 
+
+will return the following result (irrelevant attributes are omitted):
+
+```json
+{
+  "ocs": {
+    "data": {
+      "capabilities": {
+        "notes": {
+          "api_version": [ "0.2", "1.0" ]
+        }
+      }
+    }
+  }
+}
+```
+
+From Notes app version 3.3, the list of supported API versions is also provided in every response from the Notes API.
+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`.
+
+
+## Compability between minor versions
+
+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 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
+
+If a client requires a certain feature, it should check the `X-Notes-API-Versions` HTTP header of the server response.
+
+
+## Authentication
+
+Because REST is stateless you have to send user and password each time you access the API.
+Therefore running Nextcloud **with SSL is highly recommended** otherwise **everyone in your network can log your credentials**.
+
+You can test your request using `curl`:
+
+    curl -u user:password https://yournextcloud.com/index.php/apps/notes/api/v1/notes
+
+
+## Input parameters
+
+In general the input parameters can be in the URL or request body. The app framework doesn't differentiate between them.
+
+Therefore, JSON in the request body like:
+```js
+{
+  "id": 3
+}
+```
+will be treated the same as
+
+    /?id=3
+
+It is recommended though that you use the following convention:
+
+* **GET**: parameters in the URL
+* **POST**: parameters as JSON in the request body
+* **PUT**: parameters as JSON in the request body
+* **DELETE**: parameters as JSON in the request body
+
+The output is JSON.

docs/api/v1.md

@@ -0,0 +1,164 @@
+# API version 1
+
+In this document, the Notes API major version 1 and all its minor versions are described. An introduction with general information about versions, capabilities, compatibility between versions, authentication and input parameters can be found in the [README](README.md).
+
+
+## Minor versions
+
+| API version | Introduced with app version | Remarkable Changes |
+|:-----------:|:----------------------------|:-------------------|
+|  **1.0**    | Notes 3.3 (May 2020)        | Separate title, no auto rename based on content |
+
+
+
+## Note attributes
+
+The app and the API is mainly about notes. So, let's have a look about the attributes of a note. The description of endpoints and operations will refer to this attribute definition.
+
+| Attribute | Type | Description | since API version |
+|:----------|:-----|:-------------------------|:-------------------|
+| `id` | integer | Every note has a unique identifier which is created by the server. It can be used to query and update a specific note. | 1.0 |
+| `content` | string | Notes can contain arbitrary text. Formatting should be done using Markdown, but not every markup can be supported by every client. Therefore, markup should be used with care. | 1.0 |
+| `title` | string | The note's title is also used as filename for the note's file. Therefore, some special characters are automatically removed and a sequential number is added if a note with the same title in the same category exists. When saving a title, the sanitized value is returned and should be adopted by your client. | 1.0 |
+| `category` | string | Every note is assigned to a category. By default, the category is an empty string (not null), which means the note is uncategorized. Categories are mapped to folders in the file backend. Illegal characters are automatically removed and the respective folder is automatically created. Sub-categories (mapped to sub-folders) can be created by using `/` as delimiter. | 1.0 |
+| `favorite` | boolean | If a note is marked as favorite, it is displayed at the top of the notes' list. Default is `false`. | 1.0 |
+| `modified` | integer | Unix timestamp for the last modified date/time of the note. If not provided on note creation or content update, the current time is used. | 1.0 |
+
+
+## Endpoints and Operations
+
+The base URL for all calls is:
+
+    https://user:password@yournextcloud.com/index.php/apps/notes/api/v1/
+
+All defined routes in the specification are appended to this url. To access all notes for instance use this url (here shown as `curl` command):
+
+    curl -u user:password https://yournextcloud.com/index.php/apps/notes/api/v1/notes
+
+
+
+### Get all notes (`GET /notes`)
+<details><summary>Details</summary>
+
+#### Request parameters
+| Parameter | Type | Description |
+|:------|:-----|:-----|
+| `exclude` | string, optional | Fields which should be excluded from response, seperated with a comma e.g.: `?exclude=content,title`. You can use this in order to reduce transferred data size if you are interested in specific attributes, only. |
+| `purgeBefore` | integer, optional | All notes without change before of this Unix timestamp are purged from the response, i.e. only the attribute `id` is included. You should use the Unix timestamp value from the last request's HTTP response header `Last-Modified` in order to reduce transferred data size. |
+| `If-None-Match` | HTTP header, optional | Use this in order to reduce transferred data size (see [HTTP ETag](https://en.wikipedia.org/wiki/HTTP_ETag)). You should use the value from the last request's HTTP response header `ETag`. |
+
+#### Response
+##### 200 OK
+- **HTTP Header**: `ETag` (see [HTTP ETag](https://en.wikipedia.org/wiki/HTTP_ETag)).
+- **Body**: list of notes (see section [Note attributes](#note-attributes)), example:
+```js
+[
+    {
+        "id": 76,
+        "modified": 1376753464,
+        "title": "New note",
+        "category": "sub-directory",
+        "content": "New note\n and something more",
+        "favorite": false
+    }, // etc
+]
+```
+</details>
+
+
+### Get single note (`GET /notes/{id}`)
+<details><summary>Details</summary>
+
+#### Request parameters
+| Parameter | Type | Description |
+|:------|:-----|:-----|
+| `id` | integer, required (path) | ID of the note to query. |
+
+#### Response
+##### 200 OK
+- **Body**: note (see section [Note attributes](#note-attributes)), example:
+```js
+{
+    "id": 76,
+    "modified": 1376753464,
+    "title": "New note",
+    "category": "sub-directory",
+    "content": "New note\n and something more",
+    "favorite": false
+}
+```
+##### 400 Bad Request
+Invalid ID supplied.
+
+##### 404 Not Found
+Note not found.
+</details>
+
+
+### Create note (`POST /notes`)
+<details><summary>Details</summary>
+
+#### Request parameters
+- **Body**: See section [Note attributes](#note-attributes) (except for `id`).  All attributes are optional. Example: 
+```js
+{
+    "title": "New note",
+    "category": "Category/Sub Category",
+    "content": "New note\n and something more",
+}
+```
+
+#### Response
+##### 200 OK
+- **Body**: note (see section [Note attributes](#note-attributes)), example see section [Get single note](#get-single-note-get-notesid).
+
+##### 400 Bad Request
+Invalid ID supplied.
+
+##### 507 Insufficient Storage
+Not enough free storage for saving the note's content.
+</details>
+
+
+### Update note (`PUT /notes/{id}`)
+<details><summary>Details</summary>
+
+#### Request parameters
+| Parameter | Type | Description |
+|:------|:-----|:-----|
+| `id` | integer, required (path) | ID of the note to update. |
+- **Body**: See section [Note attributes](#note-attributes) (except for `id`).  All attributes are optional. Example see section [Create note](#create-note-post-notes).
+
+#### Response
+##### 200 OK
+- **Body**: note (see section [Note attributes](#note-attributes)), example see section [Get single note](#get-single-note-get-notesid).
+
+##### 400 Bad Request
+Invalid ID supplied.
+
+##### 404 Not Found
+Note not found.
+
+##### 507 Insufficient Storage
+Not enough free storage for saving the note's content.
+</details>
+
+
+### Delete note (`DELETE /notes/{id}`)
+<details><summary>Details</summary>
+
+#### Request parameters
+| Parameter | Type | Description |
+|:------|:-----|:-----|
+| `id` | integer, required (path) | ID of the note to delete. |
+
+#### Response
+##### 200 OK
+Note is deleted.
+
+##### 400 Bad Request
+Invalid ID supplied.
+
+##### 404 Not Found
+Note not found.
+</details>