fervor/entities.md

69 lines
4.4 KiB
Markdown

# Entities
All entities are UTF-8 encoded JSON objects.
## Notes
Object IDs are positive integers.
Date and DateTime fields are encoded as [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) strings.
## Instance
An Instance object provides information about the instance intself and the specific implementation of Fervor that is being used.
| Key | Description | Required |
| ------------------------ | --------------------------------------------------------- | -------- |
| `name` | String. The user-friendly name of this instance. | Yes |
| `url` | URL. The user-friendly URL of this instance. | Yes |
| `version` | String. The Fervor version this software uses. | Yes |
| `implementation_name` | String. The name of the softwre this instance is running. | Yes |
| `implementation_version` | String. The version of software this instance is running. | Yes |
| `extensions` | [Extensions object](#extensions). | No |
### Extensions
The extensions object provides additional information about extension to the Fervor API this instance provides.
There should be a field in the object for each supported extension. The key should be a unique identifier for the extension (reverse domain name style is recommended) and the value should be a URL for the extension specification or API documentation.
See the [Extensions](./extensions.md) page for more information.
## Feed
An RSS feed.
| Key | Description | Required |
| -------------- | ------------------------------------------------------------- | -------- |
| `id` | Positive Integer. The ID of this feed. | Yes |
| `title` | String. The title/name of this feed. | Yes |
| `url` | URL. The URL of the website this feed belongs to. | Yes |
| `service_url` | URL. The URL of this feed on the aggregation service. | No |
| `feed_url` | URL. The URL of the RSS document itself. | Yes |
| `last_updated` | DateTime. The last time this feed was updated by the service. | Yes |
| `group_ids` | Array of IDs. The IDs of the groups that contain this feed. | Yes |
## Item
An item is an individual item from an RSS feed.
| Key | Description | Required |
| ------------- | ------------------------------------------------------------------ | -------- |
| `id` | ID. The ID of this item. | Yes |
| `feed_id` | ID. The ID of the feed to which this item belongs. | Yes |
| `title` | String. The title of this item. | Yes |
| `author` | String. The author of this item. | No |
| `published` | DateTime. The date this item was published. | No |
| `created_at` | DateTime. The date this item was added to the aggregation service. | No |
| `content` | HTML String. The content of this item. | No |
| `summary` | HTML String. The summar of this item. | No |
| `url` | URL. The original URL of this item. | Yes |
| `service_url` | URL. The URL of this item on the aggregation service. | No |
| `read` | Boolean. Whether this item has been marked as read. | No |
## Group
A group contains multiple feeds.
Feeds may or may not belong to multiple groups, depending on the service implementation.
| Key | Description | Required |
| -------------- | ------------------------------------------------------------- | -------- |
| `id` | ID. The ID of this group. | Yes |
| `title` | String. The title/name of this group. | Yes |
| `feed_ids` | Array of IDs. The IDs of the feeds that this group contains. | Yes |
| `service_url` | URL. The URL of this group on the aggregation service. | No |