RFF5 — REST API

Request For Feature: 5

Status of this issue

This issue defines the goals of Freeder API and its specification. It is a main feature.

Introduction

From version 2.0, Freeder is organized as a web application. That means that controllers and views are managed on client side and so that communication with the server is used for only two purposes: Getting the JavaScript client and perform actions on Freeder ressources though an API.

This design will be adopted though a global refactoring so it will be an occasion to think about a potential code organization improvement. Furthermore, it will avoid problems with server-side PHP configuration like for example rewriting that will not be needed any more.

[Section 1] describes what Freeder API requires to be able to handle every front-end need and how to organize it. [Section 2] presents the effective API specification and principles. Then [Section 3] suggests a backend design that would fit this API well.

Section 1: API requirements

Every action in Freeder but getting the webapp itself is done though the API so the API MUST be able to perform any kind of action and get any data from Freeder backend.

We choosed to use REST paradigm to organize the API, and especially its explorability. All URIs represent ressources and not actions, which are provided though HTTP methods. Explorability is provided by links so that you can browse the API with the root entrypoint as only prerequisite.

Ressources

REST is ressource centric so defining a REST API requires to determine what are the main ressources of our application at first.

In Freeder, main ressources are:

• entries
• feeds
• users
• tags
• configuration options

Additionnal ressources

We add custom API entry points for themes related options and objects, although we MUST watch security issues that it could imply.

Paging

Entry sequence is a specific case since it can be very large. We SHOULD implement a paging mechanism, maybe similar to twitter API cursoring.

Expiration

In the REST philosophy, no entry points but root one need to be documented because API is self documented.

For example, root page defines base routes to main ressources. API documentation specifies entries in root page that describe ressources and these entries contains the corresponding entrypoints.

This way, the API can always evolve and be updated without changing the code using it.

But getting all pages each time to retrieve a specific route can be annoying, so there is an expiration time for pages. So root page could be stored on client side since it is used for each request to the API.

To do so, API returns information about expiration time.

For more conveniance, we add a version number in root page for API clients that relies on a specific version of the API.

Section 2: API specification

Authentication

Paging

Paging is performed though parameters given in request query string:

• page: Page to return
• count: Number of entries per page
• before: Maximum id
• after: Minimum id

Expiration

Expiration time is specified using HTTP ETags, as in YouTube API.

Example

Assuming Freeder has been installed at https://freeder.example.org, root page would return something like that:

{
	"ressources": {
		"entries": {
			"href": "https://freeder.example.org/api.php?p=entries"
		},
		"feeds": {
			"href": "https://freeder.example.org/api.php?p=feeds"
		},
		"users": {
			"href": "https://freeder.example.org/api.php?p=users"
		},
		"tags": {
			"href": "https://freeder.example.org/api.php?p=tags"
		},
		"config": {
			"href": "https://freeder.example.org/api.php?p=config"
		}
	},

	"status": {
		"installed": true,
		"version": "2.0.0"
	}
}

Since it is RESTful, URIs are presented for guidance but could be different in reality. What is important is keys. And some of them could be absent. That just means that the ressource is currently unavailable.

Section 3: Consequences on backend

Backend is based on PHP Objects for each REST ressource and some libraries provide specific functionalities.

Conclusion

This RFF needs to be completed!

Élie Michel, 11.27.2014