From a971e76b9303cae4c85f76dd9d996287797e543d Mon Sep 17 00:00:00 2001 From: korelstar Date: Mon, 13 Apr 2020 08:45:25 +0200 Subject: [PATCH 01/17] API documentation for API v1 --- docs/api/README.md | 111 +++++++++++++++++++++++++++++++++++++++++++++ docs/api/v1.md | 19 ++++++++ 2 files changed, 130 insertions(+) create mode 100644 docs/api/README.md create mode 100644 docs/api/v1.md diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 000000000..e5c211710 --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,111 @@ +# 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 specific version can be found in separate files. + + +## 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. + +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 test:test -X GET -H "OCS-APIRequest: true" -H "Accept: application/json" http://localhost/ocs/v2.php/cloud/capabilities + +will return the following result: + +```json +{ + "ocs": { + ... + "data": { + ... + "capabilities": { + ... + "notes": { + "api_version": [ + "0.2", + "1.0" + ] + }, + ... + } + } + } +} +``` + +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`. + + +## Major API versions + +TODO Table + + +## 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 v1.0 does not define the note's attribute "tags", client must ignore such a field in order to be compatible with a possible future version v1.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 v1.0 does not explicitly define response code 5xx, the client must handle + +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**. + +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: + + https://user:password@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. + diff --git a/docs/api/v1.md b/docs/api/v1.md new file mode 100644 index 000000000..8fc99e2b5 --- /dev/null +++ b/docs/api/v1.md @@ -0,0 +1,19 @@ +# API version 1 + +TODO Introduction and link to README.md + + +## Minor versions + +TODO Table + + +## Note attributes + +TODO Table + + +## Endpoints and Operations + +TODO list all endpoints + From a72de21e77b961b457dc79528d2508c351e1879b Mon Sep 17 00:00:00 2001 From: korelstar Date: Mon, 13 Apr 2020 09:47:56 +0200 Subject: [PATCH 02/17] Update README.md --- docs/api/README.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index e5c211710..b86278394 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -18,36 +18,29 @@ 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. -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). +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 test:test -X GET -H "OCS-APIRequest: true" -H "Accept: application/json" http://localhost/ocs/v2.php/cloud/capabilities -will return the following result: +will return the following result (irrelevant attributes are omitted): ```json { "ocs": { - ... "data": { - ... "capabilities": { - ... "notes": { - "api_version": [ - "0.2", - "1.0" - ] - }, - ... + "api_version": [ "0.2", "1.0" ] + } } } } } ``` -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 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`. @@ -56,7 +49,6 @@ It contains a coma-separated list of versions, e.g., `X-Notes-API-Versions: 0.2, TODO Table - ## Compability between minor versions In order to realize forward compatibility between minor versions, clients must follow some general rules regarding the API: From 050679bc459a8cf0c5184c17afa90a16f8ccd889 Mon Sep 17 00:00:00 2001 From: korelstar Date: Mon, 13 Apr 2020 14:26:48 +0200 Subject: [PATCH 03/17] Update README.md --- docs/api/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/api/README.md b/docs/api/README.md index b86278394..c992f6e2d 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -47,7 +47,10 @@ It contains a coma-separated list of versions, e.g., `X-Notes-API-Versions: 0.2, ## Major API versions -TODO Table +| Version | Supported by app version | Remarks | +|:-------:|--------------------------|---------| +| **0.2** | since 1.0 (2015) | *(deprecated)* | +| **1** | since 3.3 (April 2020) | see [documentation](v1.md) | ## Compability between minor versions From f3ed27801c18b4cc9b8fef0b6d33b72933b0ac6a Mon Sep 17 00:00:00 2001 From: korelstar Date: Mon, 13 Apr 2020 14:27:53 +0200 Subject: [PATCH 04/17] Update README.md --- docs/api/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index c992f6e2d..f012d26d9 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -47,10 +47,10 @@ It contains a coma-separated list of versions, e.g., `X-Notes-API-Versions: 0.2, ## Major API versions -| Version | Supported by app version | Remarks | -|:-------:|--------------------------|---------| -| **0.2** | since 1.0 (2015) | *(deprecated)* | -| **1** | since 3.3 (April 2020) | see [documentation](v1.md) | +| API version | Supported by app version | Remarks | +|:-----------:|--------------------------|---------| +| **0.2** | since 1.0 (2015) | *(deprecated)* | +| **1** | since 3.3 (April 2020) | see [documentation](v1.md) | ## Compability between minor versions From a1239f5ee007aa338c69fb6f1aabc838e6adb915 Mon Sep 17 00:00:00 2001 From: korelstar Date: Fri, 1 May 2020 14:08:55 +0200 Subject: [PATCH 05/17] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5b4f90428..e6e27e91f 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ 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)**. From 434c9425068bb3347d1a7fab3d11a5467b208c92 Mon Sep 17 00:00:00 2001 From: korelstar Date: Fri, 1 May 2020 14:24:22 +0200 Subject: [PATCH 06/17] Update README.md --- docs/api/README.md | 34 +++++++++++++++------------------- 1 file changed, 15 insertions(+), 19 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index f012d26d9..7d5d8672d 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -4,7 +4,15 @@ 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 specific version can be found in separate files. +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 | Remarks | +|:-----------:|--------------------------|---------| +| **1** | since 3.3 (May 2020) | **[documentation](v1.md)** | +| **0.2** | since 1.0 (2015) | *(deprecated)* | ## Versions and Capabilites @@ -22,7 +30,7 @@ From Notes app version 3.3, supported API versions can be queried using the [Nex A request like - curl -u test:test -X GET -H "OCS-APIRequest: true" -H "Accept: application/json" http://localhost/ocs/v2.php/cloud/capabilities + 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): @@ -45,19 +53,12 @@ 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`. -## Major API versions - -| API version | Supported by app version | Remarks | -|:-----------:|--------------------------|---------| -| **0.2** | since 1.0 (2015) | *(deprecated)* | -| **1** | since 3.3 (April 2020) | see [documentation](v1.md) | - ## 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 v1.0 does not define the note's attribute "tags", client must ignore such a field in order to be compatible with a possible future version v1.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 v1.0 does not explicitly define response code 5xx, the client must handle +- 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: @@ -72,18 +73,14 @@ If a client requires a certain feature, it should check the `X-Notes-API-Version 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**. -The base URL for all calls is: - - https://user:password@yournextcloud.com/index.php/apps/notes/api/v1/ +You can test your request using `curl`: -All defined routes in the specification are appended to this url. To access all notes for instance use this url: - - https://user:password@yournextcloud.com/index.php/apps/notes/api/v1/notes + 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. +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 @@ -103,4 +100,3 @@ It is recommended though that you use the following convention: * **DELETE**: parameters as JSON in the request body The output is JSON. - From 49c4b651658133744156796d22c922416735ec9d Mon Sep 17 00:00:00 2001 From: korelstar Date: Fri, 1 May 2020 14:32:30 +0200 Subject: [PATCH 07/17] Update README.md --- docs/api/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/README.md b/docs/api/README.md index 7d5d8672d..56c7e9204 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -10,7 +10,7 @@ The endpoint specification for a specific version can be found in separate files ## Major API versions | API version | Supported by app version | Remarks | -|:-----------:|--------------------------|---------| +|:-----------:|:-------------------------|:--------| | **1** | since 3.3 (May 2020) | **[documentation](v1.md)** | | **0.2** | since 1.0 (2015) | *(deprecated)* | From 08c4e2fb1e337bf72a6db83271359f611472108e Mon Sep 17 00:00:00 2001 From: korelstar Date: Fri, 1 May 2020 14:46:14 +0200 Subject: [PATCH 08/17] Update v1.md --- docs/api/v1.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/api/v1.md b/docs/api/v1.md index 8fc99e2b5..e588e0633 100644 --- a/docs/api/v1.md +++ b/docs/api/v1.md @@ -1,19 +1,36 @@ # API version 1 -TODO Introduction and link to README.md +In this document, the Notes API version 1 is 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 -TODO Table +| API version | Introduced with app version | Remarkable Changes | +|:-----------:|:-------------------------|:-------------------| +| **1.0** | 3.3 (May 2020) | Separate title, no auto rename based on content | + ## Note attributes -TODO Table +| Attribute | Type | Description | since API version | +|:----------|:-----|:-------------------------|:-------------------| +| `content` | string | TODO | 1.0 | +| `title` | string | The note's title, which is also used as filename for the note's file. Therefore, some special characters are not allowed here. When saving a title, it is automatically sanitized and the sanitized value is returned. Please be aware to adopt this value in your client. | 1.0 | +| `category` | string | TODO | 1.0 | +| `favorite` | boolean | TODO | 1.0 | +| `modified` | integer | TODO | 1.0 | ## Endpoints and Operations -TODO list all endpoints +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 + + +TODO list all endpoints From 5c5198fb59ef404f19af9d3f33ee4ad3aba912de Mon Sep 17 00:00:00 2001 From: korelstar Date: Fri, 1 May 2020 22:45:36 +0200 Subject: [PATCH 09/17] Update README.md --- docs/api/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index 56c7e9204..021e15736 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -9,10 +9,10 @@ The endpoint specification for a specific version can be found in separate files ## Major API versions -| API version | Supported by app version | Remarks | +| API version | Supported by app version | Documentation | |:-----------:|:-------------------------|:--------| -| **1** | since 3.3 (May 2020) | **[documentation](v1.md)** | -| **0.2** | since 1.0 (2015) | *(deprecated)* | +| **1** | since Notes 3.3 (May 2020) | **[Documentation](v1.md)** | +| **0.2** | since Notes 1.0 (2015) | *(deprecated)* | ## Versions and Capabilites From e51e51fc744e6dd4e50fa63f19085ba5911a8206 Mon Sep 17 00:00:00 2001 From: korelstar Date: Fri, 1 May 2020 22:47:10 +0200 Subject: [PATCH 10/17] Update v1.md --- docs/api/v1.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/api/v1.md b/docs/api/v1.md index e588e0633..ff5971356 100644 --- a/docs/api/v1.md +++ b/docs/api/v1.md @@ -1,23 +1,25 @@ # API version 1 -In this document, the Notes API version 1 is described. An introduction with general information about versions, capabilities, compatibility between versions, authentication and input parameters can be found in the [README](README.md). +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** | 3.3 (May 2020) | Separate title, no auto rename based on content | +|:-----------:|:----------------------------|:-------------------| +| **1.0** | Notes 3.3 (May 2020) | Separate title, no auto rename based on content | ## Note attributes +TODO Introduction + | Attribute | Type | Description | since API version | |:----------|:-----|:-------------------------|:-------------------| -| `content` | string | TODO | 1.0 | -| `title` | string | The note's title, which is also used as filename for the note's file. Therefore, some special characters are not allowed here. When saving a title, it is automatically sanitized and the sanitized value is returned. Please be aware to adopt this value in your client. | 1.0 | -| `category` | string | TODO | 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 not allowed here. When saving a title, it is automatically sanitized and the sanitized value is returned. Please be aware to adopt this value in your client. | 1.0 | +| `category` | string | Every note is assigned to a category or is uncategorized. In fact, uncategorized is equal to the empty category. TODO: sub-categories | 1.0 | | `favorite` | boolean | TODO | 1.0 | | `modified` | integer | TODO | 1.0 | From c00650d77517b7c876d90cd0260505f7459ddaf5 Mon Sep 17 00:00:00 2001 From: korelstar Date: Sat, 2 May 2020 20:02:53 +0200 Subject: [PATCH 11/17] Update v1.md --- docs/api/v1.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/v1.md b/docs/api/v1.md index ff5971356..46d3523f1 100644 --- a/docs/api/v1.md +++ b/docs/api/v1.md @@ -13,13 +13,13 @@ In this document, the Notes API major version 1 and all its minor versions are d ## Note attributes -TODO Introduction +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 | |:----------|:-----|:-------------------------|:-------------------| | `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 not allowed here. When saving a title, it is automatically sanitized and the sanitized value is returned. Please be aware to adopt this value in your client. | 1.0 | -| `category` | string | Every note is assigned to a category or is uncategorized. In fact, uncategorized is equal to the empty category. TODO: sub-categories | 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. TODO: sub-categories | 1.0 | | `favorite` | boolean | TODO | 1.0 | | `modified` | integer | TODO | 1.0 | From 552c3c9c8366728c87ba72fb4bce7dbae0909d67 Mon Sep 17 00:00:00 2001 From: korelstar Date: Tue, 5 May 2020 07:58:51 +0200 Subject: [PATCH 12/17] Update v1.md --- docs/api/v1.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 121 insertions(+), 4 deletions(-) diff --git a/docs/api/v1.md b/docs/api/v1.md index 46d3523f1..e8e00867d 100644 --- a/docs/api/v1.md +++ b/docs/api/v1.md @@ -17,11 +17,12 @@ The app and the API is mainly about notes. So, let's have a look about the attri | 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. TODO: sub-categories | 1.0 | -| `favorite` | boolean | TODO | 1.0 | -| `modified` | integer | TODO | 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 @@ -35,4 +36,120 @@ All defined routes in the specification are appended to this url. To access all curl -u user:password https://yournextcloud.com/index.php/apps/notes/api/v1/notes -TODO list all endpoints + +### Get all notes (`GET /notes`) + +#### 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 *Notes attributes*), example: +```js +[ + { + "id": 76, + "modified": 1376753464, + "title": "New note", + "category": "sub-directory", + "content": "New note\n and something more", + "favorite": false + }, // etc +] +``` + + +### Get single note (`GET /notes/{id}`) + +#### Request parameters +| Parameter | Type | Description | +|:------|:-----|:-----| +| `id` | integer, required (path) | ID of the note to query. | + +#### Response +##### 200 OK +- **Body**: note (see section *Notes 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. + + +### Create note (`POST /notes`) + +#### Request parameters +- **Body**: See section *Notes 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 *Notes attributes*), example see section *Get single note*. + +##### 400 Bad Request +Invalid ID supplied. + +##### 507 Insufficient Storage +Not enough free storage for saving the note's content. + + + +### Update note (`PUT /notes/{id}`) + +#### Request parameters +| Parameter | Type | Description | +|:------|:-----|:-----| +| `id` | integer, required (path) | ID of the note to update. | +- **Body**: See section *Notes attributes* (except for `id`). All attributes are optional. Example see section *Create note*. + +#### Response +##### 200 OK +- **Body**: note (see section *Notes attributes*), example see section *Get single note*. + +##### 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. + + +### Delete note (`DELETE /notes/{id}`) + +#### 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. From e11f2afd771d2d1af5ab9c5ad84f7d6b03b3ac7f Mon Sep 17 00:00:00 2001 From: korelstar Date: Tue, 5 May 2020 08:22:26 +0200 Subject: [PATCH 13/17] Update v1.md --- docs/api/v1.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/api/v1.md b/docs/api/v1.md index e8e00867d..c7b55492d 100644 --- a/docs/api/v1.md +++ b/docs/api/v1.md @@ -38,6 +38,7 @@ All defined routes in the specification are appended to this url. To access all ### Get all notes (`GET /notes`) +
Details #### Request parameters | Parameter | Type | Description | @@ -62,9 +63,11 @@ All defined routes in the specification are appended to this url. To access all }, // etc ] ``` +
### Get single note (`GET /notes/{id}`) +
Details #### Request parameters | Parameter | Type | Description | @@ -89,9 +92,11 @@ Invalid ID supplied. ##### 404 Not Found Note not found. +
### Create note (`POST /notes`) +
Details #### Request parameters - **Body**: See section *Notes attributes* (except for `id`). All attributes are optional. Example: @@ -112,10 +117,11 @@ Invalid ID supplied. ##### 507 Insufficient Storage Not enough free storage for saving the note's content. - +
### Update note (`PUT /notes/{id}`) +
Details #### Request parameters | Parameter | Type | Description | @@ -135,9 +141,11 @@ Note not found. ##### 507 Insufficient Storage Not enough free storage for saving the note's content. +
### Delete note (`DELETE /notes/{id}`) +
Details #### Request parameters | Parameter | Type | Description | @@ -153,3 +161,4 @@ Invalid ID supplied. ##### 404 Not Found Note not found. +
From 239a5241717b5f99c38b6060c443cbfbe72f2fa7 Mon Sep 17 00:00:00 2001 From: korelstar Date: Tue, 5 May 2020 08:25:19 +0200 Subject: [PATCH 14/17] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e6e27e91f..e1ee5e7fc 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Before reporting bugs: [![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) -**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 +39,7 @@ Before reporting bugs: 4. Enable the app through the app management of your Nextcloud -**REST API for third-party apps** +### REST API for third-party apps The notes app provides a JSON-API for third-party apps. Please have a look at our **[API documentation](docs/api/README.md)**. From 177d6ccfbc2a61460109cdd41d103f17e1e48789 Mon Sep 17 00:00:00 2001 From: korelstar Date: Tue, 5 May 2020 16:37:38 +0200 Subject: [PATCH 15/17] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e1ee5e7fc..09ec49a6e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Notes -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,6 +29,7 @@ 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 @@ -42,4 +43,3 @@ Before reporting bugs: ### REST API for third-party apps The notes app provides a JSON-API for third-party apps. Please have a look at our **[API documentation](docs/api/README.md)**. - From 08cfc7a2321153d7d0326266a55de0a1df9d24d7 Mon Sep 17 00:00:00 2001 From: korelstar Date: Tue, 5 May 2020 16:38:22 +0200 Subject: [PATCH 16/17] Update info.xml --- appinfo/info.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/appinfo/info.xml b/appinfo/info.xml index e0f970b6b..7f6cbd5db 100644 --- a/appinfo/info.xml +++ b/appinfo/info.xml @@ -5,7 +5,7 @@ Notes Distraction-free notes and writing 3.2.0 agpl From 9701f3800a1ae7881462e996b5d3c7412ee67611 Mon Sep 17 00:00:00 2001 From: korelstar Date: Tue, 5 May 2020 16:48:38 +0200 Subject: [PATCH 17/17] Update v1.md --- docs/api/v1.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/v1.md b/docs/api/v1.md index c7b55492d..c641820ff 100644 --- a/docs/api/v1.md +++ b/docs/api/v1.md @@ -50,7 +50,7 @@ All defined routes in the specification are appended to this url. To access all #### Response ##### 200 OK - **HTTP Header**: `ETag` (see [HTTP ETag](https://en.wikipedia.org/wiki/HTTP_ETag)). -- **Body**: list of notes (see section *Notes attributes*), example: +- **Body**: list of notes (see section [Note attributes](#note-attributes)), example: ```js [ { @@ -76,7 +76,7 @@ All defined routes in the specification are appended to this url. To access all #### Response ##### 200 OK -- **Body**: note (see section *Notes attributes*), example: +- **Body**: note (see section [Note attributes](#note-attributes)), example: ```js { "id": 76, @@ -99,7 +99,7 @@ Note not found.
Details #### Request parameters -- **Body**: See section *Notes attributes* (except for `id`). All attributes are optional. Example: +- **Body**: See section [Note attributes](#note-attributes) (except for `id`). All attributes are optional. Example: ```js { "title": "New note", @@ -110,7 +110,7 @@ Note not found. #### Response ##### 200 OK -- **Body**: note (see section *Notes attributes*), example see section *Get single note*. +- **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. @@ -127,11 +127,11 @@ Not enough free storage for saving the note's content. | Parameter | Type | Description | |:------|:-----|:-----| | `id` | integer, required (path) | ID of the note to update. | -- **Body**: See section *Notes attributes* (except for `id`). All attributes are optional. Example see section *Create note*. +- **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 *Notes attributes*), example see section *Get single note*. +- **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.