path: root/docs/api/api-v1-3.md

# External API v1-3

The **News app 1.3** offers a RESTful API.

## API stability contract

The API level will **change** if the following occurs:

* A field of an object is removed
* A field of an object has a different datatype
* The meaning of an API call changes

The API level will **not change** if:

* The app version is changed (e.g. 4.0.1.2 instead of 4.0 or 4.001)
* A new attribute is added (e.g. each item gets a new field "something": 1)
* The order of the JSON attributes is changed on any level (e.g. "id":3 is not the first field anymore, but the last)

You have to design your app with these things in mind!:

* **Don't depend on the order of object attributes. In JSON it does not matter where the object attribute is since you access the value by name, not by index**
* **Don't limit your app to the currently available attributes. New ones might be added. If you don't handle them, ignore them**
* **Use a library to compare versions, ideally one that uses semantic versioning**

## Authentication & Basics
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://yournextcloud.com/index.php/apps/news/api/v1-3/

All defined routes in the Specification are appended to this url. To access all feeds for instance use this url:

    https://yournextcloud.com/index.php/apps/news/api/v1-3/feeds

Credentials need to be passed as an HTTP header using [HTTP basic auth](https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side):

    Authorization: Basic $CREDENTIALS

where $CREDENTIALS is:

    base64(USER:PASSWORD)

## How To Sync
This is a small overview over how you should sync your articles with the Nextcloud News app. For more fine-grained details about the API see further down.

All routes are given relative to the base API url (e.g.: https://yournextcloud.com/index.php/apps/news/api/v1-3)

### Initial Sync
The intial sync happens, when a user adds a Nextcloud account in your app. In that case you should fetch all feeds, folders and unread or starred articles from the News app. Do not fetch all articles, not only because it syncs faster, but also because the user is primarily interested in unread articles. To fetch all unread and starred articles, you must call 4 routes:

* **unread articles**: GET /items?type=3&getRead=false&batchSize=-1
* **starred articles**: GET /items?type=2&getRead=true&batchSize=-1
* **folders**: GET /folders
* **feeds**: GET /feeds

The JSON response structures can be viewed further down.

### Syncing
When syncing, you want to push read/unread and starred/unstarred items to the server and receive new and updated items, feeds and folders. To do that, call the following routes:

* **Notify the News app of unread articles**: PUT /items/unread/multiple {"items": [1, 3, 5]}
* **Notify the News app of read articles**: PUT /items/read/multiple {"items": [1, 3, 5]}
* **Notify the News app of starred articles**: PUT /items/starred/multiple {"itemIds": [1, 3, 5]}
* **Notify the News app of unstarred articles**: PUT /items/unstarred/multiple {"itemIds": [1, 3, 5]}
* **Get new folders**: GET /folders
* **Get new feeds**: GET /feeds
* **Get new items and modified items**: GET /items/updated?lastModified=12123123123&type=3


## Accessing API from a web application

**News 1.401** implements CORS which allows web applications to access the API. **To access the API in a webapp you need to send the correct authorization header instead of simply putting auth data into the URL!**. An example request in jQuery would look like this:

```js
$.ajax({
	type: 'GET',
	url: 'https://yournextcloud.com/index.php/apps/news/api/v1-3/version',
	contentType: 'application/json',
	success: function (response) {
		// handle success
	},
	error: function () {
		// handle errors
	},
	beforeSend: function (xhr) {
		var username = 'john';
		var password = 'doe';
		var auth = btoa(username + ':' + password);
		xhr.setRequestHeader('Authorization', 'Basic ' + auth);
	}
});
```
An example with AngularJS would look like this:
```js
angular.module('YourApp', [])
    .config(['$httpProvider', '$provide', function ($httpProvider, $provide) {
        $provide.factory('AuthInterceptor', ['Credentials', '$q', function (Credentials, $q) {
            return {
                request: function (config) {
                    // only set auth headers if url matches the api url
                    if(config.url.indexOf(Credentials.url) === 0) {
                        auth = btoa(Credentials.userName + ':' + Credentials.password);
                        config.headers['Authorization'] = 'Basic ' + auth;
                    }
                    return config || $q.when(config);
                }
            };
        }]);
        $httpProvider.interceptors.push('AuthInterceptor');
    }])
    .factory('Credentials', function () {
        return {
            userName: 'user',
            password: 'password',
            url: 'https://yournextcloud.com/index.php/apps/news/api'
        };
    })
    .run(['$http', function($http) {
        $http({
            method: 'GET',
            url: 'https://yournextcloud.com/index.php/apps/news/api/v1-3/version'
        }).success(function (data, status, header, config) {
            // handle success
        }).error(function (data, status, header, config) {
            // handle error
        });
    }]);
```

## Input
In general the input parameters can be in the URL or request body, the App Framework doesnt differentiate between them.

So JSON in the request body like:
```jsonc
{
  "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

## Output
The output is JSON.

## API Endpoints

### Folders
#### Get all folders

* **Status**: Implemented
* **Method**: GET
* **Route**: /folders
* **Parameters**: none
* **Returns**:
```jsonc
{
  "folders": [
    {
      "id": 4,
      "name": "Media"
    }, // etc
  ]
}
```

#### Create a folder
Creates a new folder and returns a new folder object

* **Status**: Implemented
* **Method**: POST
* **Route**: /folders
* **Parameters**:
```jsonc
{
  "name": "folder name"
}
```
* **Return codes**:
 * **HTTP 409**: If the folder exists already
 * **HTTP 422**: If the folder name is invalid (for instance empty)
* **Returns**:
```jsonc
{
  "folders": [
    {
      "id": 4,
      "name": "Media"
    }
  ]
}
```

#### Delete a folder
Deletes a folder with the id folderId and all the feeds it contains

* **Status**: Implemented
* **Method**: DELETE
* **Route**: /folders/{folderId}
* **Parameters**: none
* **Return codes**:
 * **HTTP 404**: If the folder does