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

Everything but getting the webapp 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.

Adopted ressources:

• entry
• feed
• user
• tag
• config

Getting sequences : how to limit ? Cursoring ? Or not ? Expiration => Example of use of caching for REST API

Custom API entry points for themes. Watch security issues.

Section 2: API specification

Entry point Relation description (hrefs) Authentication Paging Expiration

Assuming Freeder has been installed at https://freeder.example.org

{
	"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, convention are presented for guidance If the entrypoint you use dos not come from an href that is not beyond expiration time, don't be surprised if it does not work. Warranties for root only.

Section 3: Consequences on backens

=> Object Oriented organized around REST ressources

Conclusion

Élie Michel, 11.27.2014