fervor/extensions.md

Extensions

Since the Fervor API is designed to be a common foundation, it doesn't include all of the features that implementors might want. As such, it's designed to be extensible.

When extending the API, several factors should be taken into account to prevent naming conflicts.

Extension Identifiers

Each extension should have its own unique identifier. It's recommended that these be reverse domain names (e.g. com.example.fervor.tags).

Announcing Extensions

Implementations make their extensions known by including them in the Extensions sub-object in the Instance object.

For each extension provided, there should be a field in the Extensions object with their identifier as the key and the URL of their specification/documentation as the value.

Extended Entities

Extensions may include additional data in any of the Entities. To avoid name conflicts, all extension data should be contained in a sub-object of the entity whose key is the extension identifier.

For example, an extended item object:

{
	"id": 1,
	"feed_id": 1,
	"title": "Example",
	"url": "https://example.com",
	"com.example.fervor.tags": {
		"favorite": true,
		"tags": [1, 3]
	}
}

Extended Endpoints

Extensions may also provide additional API endpoints that provide access to their specific data. To avoid name conflicts, all extension endpoints should be under /api/<identifier>/.

For example, the com.example.fervor.tags extension may provide a GET endpoint at /api/com.example.fervor.tags/v1/tags that returns an array of all tag objects.

Extended Requests

Extensions may also accept additional parameters in Fervor requests. To avoid name conflicts, all extension parameters should be prefixed with the extension identifier.

For example, the com.example.fervor.tags extension may extend the feed creation endpoint with a com.example.fervor.tags.new parameter that accepts a list of tags to assign to the newly created feed.