summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBenjamin Brahmer <info@b-brahmer.de>2021-05-12 12:08:19 +0200
committerBenjamin Brahmer <info@b-brahmer.de>2021-05-12 12:08:19 +0200
commitdf023fadebc227030c61be73eda943d4bf013236 (patch)
tree6ae0bb2e3ee915faf46c0b669cce43cbe608c5ec
parent8727f6b8a4b05c44391ca0140fef9d5be7b74e1a (diff)
fix format
Signed-off-by: Benjamin Brahmer <info@b-brahmer.de>
-rw-r--r--docs/api/api-v2.md35
-rw-r--r--docs/features/plugins.md2
2 files changed, 37 insertions, 0 deletions
diff --git a/docs/api/api-v2.md b/docs/api/api-v2.md
index ecc23338c..c5fee3806 100644
--- a/docs/api/api-v2.md
+++ b/docs/api/api-v2.md
@@ -17,6 +17,7 @@ This document uses the following conventions:
In order to only specify the JSON objects once, comments are used to alias them.
There are two types of aliases:
+
* Objects
* Object arrays
@@ -86,12 +87,15 @@ Unless an absolute Url is specified, the relative Urls in the Specification are
https://yournextcloud.com/index.php/apps/news/api/v2/sync
The required request headers are:
+
* **Accept**: application/json
Any request method except GET:
+
* **Content-Type**: application/json; charset=utf-8
Any route that allows caching:
+
* **If-None-Match**: an Etag, e.g. 6d82cbb050ddc7fa9cbb659014546e59. If no previous Etag is known, this header should be omitted
The request body is either passed in the URL in case of a **GET** request (e.g.: **?foo=bar&index=0**) or as JSON, e.g.:
@@ -127,18 +131,21 @@ This authentication/authorization method will be the recommended default until c
The status codes are not always provided by the News app itself, but might also be returned because of Nextcloud internal errors.
The following status codes can always be returned by Nextcloud:
+
* **401**: The provided credentials to log into Nextcloud are invalid.
* **403**: The user is not allowed to access the route. This can happen if for instance of only users in the admin group can access the route and the user is not in it.
* **404**: The route can not be found or the resource does not exist. Can also happen if for instance you are trying to delete a folder which does not exist.
* **5xx**: An internal server error occurred. This can happen if the server is in maintenance mode or because of other reasons.
The following status codes are returned by News:
+
* **200**: Everything went fine
* **304**: In case the resource was not modified, contains no response body. This means that you can ignore the request since everything is up to date.
* **400**: There was an app related error, check the **error** object if specified
* **409**: Conflict error which means that the resource exists already. Can be returned when updating (**PATCH**) or creating (**POST**) a resource, e.g. a folder
The response headers are:
+
* **Content-Type**: application/json; charset=utf-8
* **Etag**: A string containing a cache header of maximum length 64, e.g. 6d82cbb050ddc7fa9cbb659014546e59. The etag value will be assembled using the number of feeds, folders and the highest last modified timestamp in milliseconds, e.g. 2-3-123131923912392391239. However consider that a detail and dont rely on it.
@@ -161,6 +168,7 @@ In case of an **4xx** or **5xx** error the request was not successful and has to
## Security Guidelines
Read the following notes carefully to prevent being subject to security exploits:
+
* You should always enforce SSL certificate verification and never offer a way to turn it off. Certificate verification is important to prevent MITM attacks which is especially important in the mobile world where users are almost always connected to untrusted networks. In case a user runs a self-signed certificate on his server ask him to either install his certificate on his device or direct him to one of the many ways to sign his certificate for free (most notably letsencrypt.com)
* All string fields in a JSON response **expect an item's body** are **not sanitized**. This means that if you do not escape it properly before rendering you will be vulnerable to [XSS](https://www.owasp.org/index.php/Cross-site_Scripting_%28XSS%29) attacks
* Basic Auth headers can easily be decrypted by anyone since base64 is an encoding, not an encryption. Therefore only send them if you are accessing an HTTPS website or display an easy to understand warning if the user chooses HTTP
@@ -171,6 +179,7 @@ Read the following notes carefully to prevent being subject to security exploits
All routes are given relative to the base API url, e.g.: **/sync** becomes **https://yourNextcloud.com/index.php/apps/news/api/v2/sync**
There are two usecases for syncing:
+
* **Initial sync**: the user does not have any data at all
* **Syncing local and remote changes**: the user has synced at least once and wants to submit and receive changes
@@ -184,9 +193,11 @@ The intial sync happens when a user adds an Nextcloud account in your app. In th
* **Accept: "application/json"**
This will return the following status codes:
+
* **200**: Success
and the following HTTP headers:
+
* **Content-Type**: application/json; charset=utf-8
* **Etag**: A string containing a cache header, maximum size 64 ASCII characters, e.g. 6d82cbb050ddc7fa9cbb659014546e59
@@ -200,6 +211,7 @@ and the following request body:
```
**Note**: Each object is explained in more detail in a separate section:
+
* [Folders](#folders)
* [Feeds](#feeds)
* [Items](#items)
@@ -249,6 +261,7 @@ If no items have been read or starred, simply leave the **items** array empty, e
```
The response matches the **GET** call, except there can be two different types of item objects:
+
* **[Full](#full)**: Contains all attributes
* **[Reduced](#reduced)**: Contains only **id**, **isUnread** and **isStarred**
@@ -310,11 +323,13 @@ Folders are represented using the following data structure:
```
The attributes mean the following:
+
* **id**: 64bit Integer, id
* **name**: Abitrary long text, folder's name
### Deleting A Folder
To delete a folder, use the following request:
+
* **Method**: DELETE
* **Route**: /folders/{id}
* **Route Parameters**:
@@ -324,6 +339,7 @@ To delete a folder, use the following request:
The following response is being returned:
Status codes:
+
* **200**: Folder was deleted successfully
* **404**: Folder does not exist
@@ -341,6 +357,7 @@ In case of an HTTP 200, the deleted folder is returned in full in the response,
### Creating A Folder
To create a folder, use the following request:
+
* **Method**: POST
* **Route**: /folders
* **Authentication**: [required](#authentication)
@@ -355,6 +372,7 @@ with the following request body:
The following response is being returned:
Status codes:
+
* **200**: Folder was created successfully
* **400**: Folder creation error, check the error object:
* **code**: 1: folder name is empty
@@ -369,9 +387,11 @@ In case of an HTTP 200, the created or already existing folder is returned in fu
### Changing A Folder
The following attributes can be changed on the folder:
+
* **name**
To change any number of attributes on a folder, use the following request and provide as much attributes that can be changed as you want:
+
* **Method**: PATCH
* **Route**: /folders/{id}
* **Route Parameters**:
@@ -390,6 +410,7 @@ with the following request body:
The following response is being returned:
Status codes:
+
* **200**: Folder was updated successfully
* **400**: Folder update error, check the error object:
* **code**: 1: folder name is empty
@@ -425,6 +446,7 @@ Feeds are represented using the following data structure:
```
The attributes mean the following:
+
* **id**: 64bit Integer, id
* **name**: Abitrary long text, feed's name
* **faviconLink**: Abitrary long text, feed's favicon location, **null** if not found
@@ -445,6 +467,7 @@ The attributes mean the following:
### Deleting A Feed
To delete a feed, use the following request:
+
* **Method**: DELETE
* **Route**: /feeds/{id}
* **Route Parameters**:
@@ -455,6 +478,7 @@ To delete a feed, use the following request:
The following response is being returned:
Status codes:
+
* **200**: Feed was deleted successfully
* **404**: Feed with given id was not found, no error object
* Other Nextcloud errors, see [Response Format](#response-format)
@@ -474,6 +498,7 @@ In case of an HTTP 200, the deleted feed is returned in full in the response, e.
### Creating A feed
To create a feed, use the following request:
+
* **Method**: POST
* **Route**: /feeds
* **Authentication**: [required](#authentication)
@@ -492,6 +517,7 @@ with the following request body:
"basicAuthPassword": "password"
}
```
+
* **url**: Abitrary long text, the url needs to have the full schema e.g. https://the-url.com. In case the user omits the schema, prepending **https** is recommended
* **folderId**: 64bit Integer, the feed's folder or **0** in case no folder is specified
* **name (optional)**: Abitrary long text, the feeds name or if not given taken from the RSS/Atom feed
@@ -505,6 +531,7 @@ with the following request body:
The following response is being returned:
Status codes:
+
* **200**: Feed was created successfully
* **400**: Feed creation error, check the **error** object:
* **code**: 1: url is empty
@@ -531,6 +558,7 @@ In case of an HTTP 200, the created feed is returned in full in the response, e.
### Changing A Feed
To change a feed, use the following request:
+
* **Method**: PATCH
* **Route**: /feeds/{id}
* **Route Parameters**:
@@ -566,6 +594,7 @@ All parameters are optional
The following response is being returned:
Status codes:
+
* **200**: Feed was changed successfully
* **400**: Feed creation error, check the error object:
* **code**: 1: url is empty
@@ -599,6 +628,7 @@ Items can occur in two different formats:
* Reduced
The attributes mean the following:
+
* **id**: 64bit Integer, id
* **url**: Abitrary long text, location of the online resource
* **title**: Abitrary long text, item's title
@@ -707,6 +737,7 @@ Both APIs will return the following response body or terminal output:
After all feed ids and user ids are known, feeds can be updated in parallel.
**Console API**:
+
* **Positional Parameters**:
* **{feedId}**: the feed's id
* **{userId}**: the user's id
@@ -748,6 +779,7 @@ The retrieve meta data about the app, use the following request:
The following response is being returned:
Status codes:
+
* **200**: Meta data accessed successfully
In case of an HTTP 200, the the following response is returned:
@@ -770,6 +802,7 @@ In case of an HTTP 200, the the following response is returned:
```
The attributes mean the following:
+
* **version**: Abitrary long text, News app version
* **issues**: An object containing a dictionary of issues which need to be displayed to the user:
* **improperlyConfiguredCron**: Boolean, if true this means that no feed updates are run on the server because the updater is misconfigured
@@ -791,6 +824,7 @@ To find out which API levels are supported, make a request to the following rout
The following response is being returned:
Status codes:
+
* **200**: The supported API levels can be parsed from the response
* **404**: The user is either running a version prior to **8.8.0** or the News app is disabled or not installed.
@@ -810,6 +844,7 @@ To find out if a user is running an older News version than **8.8.0**, make a re
* **Authentication**: [required](#authentication)
Status codes:
+
* **200**: Only the v1-2 API level is supported
* **404**: The News app is disabled or not installed.
diff --git a/docs/features/plugins.md b/docs/features/plugins.md
index 1b1dfee33..25a22748a 100644
--- a/docs/features/plugins.md
+++ b/docs/features/plugins.md
@@ -201,6 +201,8 @@ Using automatic container assembly you can then use it from your code by simply
### Examples
Client-side plugins:
+
* [Mail Share](https://github.com/cosenal/mailsharenewsplugin): Client-side plugin to share articles by email
Server-side plugins:
+
* [Feed Central](https://github.com/Raydiation/feedcentral): Publish your feeds as RSS