Additional management endpoints

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.
 
@@ -53,4 +119,30 @@ Returns the Item object for the given ID.
 Marks the Item with the given ID as read.
 
 ### `POST /api/v1/items/:id/unread`
-Marks the Item with the given ID as 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.

extensions.md

@@ -32,4 +32,9 @@ For example, an extended item object:
 ## 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.
+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.