Additional management endpoints
This commit is contained in:
parent
b2b70ba0c9
commit
70f9efd397
GPG Key ID:
94A5AB95422746E5
96
endpoints.md
96
endpoints.md
|
|
@ -1,5 +1,15 @@
|
|||
# API Endpoints
|
||||
|
||||
## Note on Responses
|
||||
All successful API calls must result in an HTTP 200 OK response whose body is the UTF-8 encoded JSON of the response data.
|
||||
|
||||
Error responses must result in non-200 response (it is recommended to use the appropriate HTTP error code when possible) whose body is a JSON object structured like so:
|
||||
|
||||
| Key | Description | Required |
|
||||
| ------------------- | --------------------------------------------------------------------------------------------- | -------- |
|
||||
| `error` | String. The main error message. Should be fairly short and should be presentable to the user. | Yes |
|
||||
| `error_description` | String. A more verbose/technical description of the error. | No |
|
||||
|
||||
## Server Instance
|
||||
### `GET /api/v1/instance`
|
||||
Returns an Instance object containing information about this instance and this Fervor implementation.
|
||||
|
|
@ -23,11 +33,34 @@ Equivalent to retrieving the Group object and then looking up all the feeds spec
|
|||
|
||||
Returns an array of the most recent Items (read or unread) from all the feeds in this group.
|
||||
|
||||
#### Parameters
|
||||
#### Query Parameters
|
||||
| Key | Description | Required |
|
||||
| ------ | ------------------------------------------------------------------------------------------------------------ | -------- |
|
||||
| `only` | String. One of `read` or `unread`. Only the given type of items will be returned, or both types, if omitted. | No |
|
||||
|
||||
### `POST /api/v1/groups/create`
|
||||
Creates a new Group from the given parameters.
|
||||
|
||||
#### Parameters
|
||||
Parameters should be sent as `application/x-www-form-urlencoded` in the POST body.
|
||||
|
||||
| Key | Description | Required |
|
||||
| ---------- | ----------------------------------------------------------------------------------------------- | -------- |
|
||||
| `title` | String. The title of this group. | Yes |
|
||||
| `feed_ids` | String of comma-delimited Integers. The IDs of any already existing feeds to add to this group. | No |
|
||||
|
||||
#### Response
|
||||
If group creation was successful, the server will return the new Group object.
|
||||
|
||||
**Note:** Specific server implementations may require additional information to be provided, so a request with the bare minimum parameters may not be successful.
|
||||
|
||||
### `POST /api/v1/groups/:id/delete`
|
||||
Deletes the group with the given ID. In some server implementations, this request may also delete all feeds belonging to the deleted group.
|
||||
|
||||
No parameters.
|
||||
|
||||
If successful, the server will respond with an HTTP 410 Gone response.
|
||||
|
||||
## Feeds
|
||||
### `GET /api/v1/feeds/`
|
||||
Returns an array of all available Feed objects.
|
||||
|
|
@ -40,12 +73,45 @@ Returns the Feed object for the given ID.
|
|||
|
||||
Returns an array of the most recent Items (read or unread) from this feed.
|
||||
|
||||
#### Parameters
|
||||
#### Query Parameters
|
||||
| Key | Description | Required |
|
||||
| ------ | ------------------------------------------------------------------------------------------------------------ | -------- |
|
||||
| `only` | String. One of `read` or `unread`. Only the given type of items will be returned, or both types, if omitted. | No |
|
||||
|
||||
### `POST /api/v1/feeds/create`
|
||||
Creates a new Feed from the given parameters.
|
||||
|
||||
#### Parameters
|
||||
Parameters should be sent as `application/x-www-form-urlencoded` in the POST body.
|
||||
|
||||
| Key | Description | Required |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------ | -------- |
|
||||
| `feed_url` | URL. The URL of the RSS document for this feed. | Yes |
|
||||
| `group_ids` | String of comma-delimited Integers. The IDs of any already existing groups that this feed should be part of. | No |
|
||||
|
||||
#### Response
|
||||
If feed creation was successful, the server will return the new Feed object.
|
||||
|
||||
**Note:** Specific server implementations may require additional information to be provided, so a request with the bare minimum parameters may not be successful.
|
||||
|
||||
### `POST /api/v1/feeds/:id/delete`
|
||||
Deletes the feed with the given ID.
|
||||
|
||||
No parameters.
|
||||
|
||||
If successful, the server will return respond with an HTTP 410 Gone response.
|
||||
|
||||
## Items
|
||||
### `GET /api/v1/items`
|
||||
[Paginated](./pagination.md).
|
||||
|
||||
Returns an array of all the Items that belong to the user.
|
||||
|
||||
#### Query Parameters
|
||||
| Key | Description | Required |
|
||||
| ------ | ------------------------------------------------------------------------------------------------------------ | -------- |
|
||||
| `only` | String. One of `read` or `unread`. Only the given type of items will be returned, or both types, if omitted. | No |
|
||||
|
||||
### `GET /api/v1/items/:id`
|
||||
Returns the Item object for the given ID.
|
||||
|
||||
|
|
@ -54,3 +120,29 @@ Marks the Item with the given ID as read.
|
|||
|
||||
### `POST /api/v1/items/:id/unread`
|
||||
Marks the Item with the given ID as unread.
|
||||
|
||||
### `POST /api/v1/items/read`
|
||||
Marks all Items with the given IDs as read.
|
||||
|
||||
Server implementations may optionally enforce a limit of how many posts may be marked as read with one API call.
|
||||
|
||||
#### Query Parameters
|
||||
| Key | Description | Required |
|
||||
| ----- | ----------------------------------------------------------------------------- | -------- |
|
||||
| `ids` | String of comma delimited Integers. The IDs of all the posts to mark as read. | Yes |
|
||||
|
||||
#### Response
|
||||
Returns an array of all the item IDs that were _successfully_ marked as read.
|
||||
|
||||
### `POST /api/v1/items/unread`
|
||||
Marks all Items with the given IDs as unread.
|
||||
|
||||
Server implementations may optionally enforce a limit of how many posts may be marked as unread with one API call.
|
||||
|
||||
#### Query Parameters
|
||||
| Key | Description | Required |
|
||||
| ----- | ------------------------------------------------------------------------------- | -------- |
|
||||
| `ids` | String of comma delimited Integers. The IDs of all the posts to mark as unread. | Yes |
|
||||
|
||||
#### Response
|
||||
Returns an array of all the item IDs that were _successfully_ marked as unread.
|
||||
|
|
@ -33,3 +33,8 @@ For example, an extended item object:
|
|||
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.
|
||||
Loading…
Reference in New Issue