From e92a1cf436b99757e82d0234ca54b6c41b7ddb16 Mon Sep 17 00:00:00 2001 From: Eugen Rochko Date: Sat, 21 Jan 2017 22:49:08 +0100 Subject: Add wiki contents to docs/ instead --- docs/Using-the-API/API.md | 277 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 277 insertions(+) create mode 100644 docs/Using-the-API/API.md (limited to 'docs/Using-the-API/API.md') diff --git a/docs/Using-the-API/API.md b/docs/Using-the-API/API.md new file mode 100644 index 000000000..81225d716 --- /dev/null +++ b/docs/Using-the-API/API.md @@ -0,0 +1,277 @@ +# Contents + +- [Available libraries](#available-libraries) +- [Notes](#notes) +- [Methods](#methods) + - Posting a status + - Uploading media + - Retrieving a timeline + - Retrieving notifications + - Following a remote user + - Fetching data + - Deleting a status + - Reblogging a status + - Favouriting a status + - Threads (status context) + - Who reblogged/favourited a status + - Following/unfollowing accounts + - Blocking/unblocking accounts + - Creating OAuth apps +- [Entities](#entities) + - Status + - Account +- [Pagination](#pagination) + +# Available libraries + +- [For Ruby](https://github.com/tootsuite/mastodon-api) +- [For Python](https://github.com/halcy/Mastodon.py) +- [For JavaScript](https://github.com/Zatnosk/libodonjs) +- [For JavaScript (Node.js)](https://github.com/jessicahayley/node-mastodon) + +# Notes + +When an array parameter is mentioned, the Rails convention of specifying array parameters in query strings is meant. For example, a ruby array like `foo = [1, 2, 3]` can be encoded in the params as `foo[]=1&foo[]=2&foo[]=3`. Square brackets can be indexed but can also be empty. + +When a file parameter is mentioned, a form-encoded upload is expected. + +# Methods +## Posting a new status + +**POST /api/v1/statuses** + +Form data: + +- `status`: The text of the status +- `in_reply_to_id` (optional): local ID of the status you want to reply to +- `media_ids` (optional): array of media IDs to attach to the status (maximum 4) +- `sensitive` (optional): set this to mark the media of the status as NSFW +- `visibility` (optional): either `private`, `unlisted` or `public` + +Returns the new status. + +**POST /api/v1/media** + +Form data: + +- `file`: Image to be uploaded + +Returns a media object with an ID that can be attached when creating a status (see above). + +## Retrieving a timeline + +**GET /api/v1/timelines/home** +**GET /api/v1/timelines/mentions** +**GET /api/v1/timelines/public** +**GET /api/v1/timelines/tag/:hashtag** + +Returns statuses, most recent ones first. Home timeline is statuses from people you follow, mentions timeline is all statuses that mention you. Public timeline is "whole known network", and the last is the hashtag timeline. + +Query parameters: + +- `max_id` (optional): Skip statuses younger than ID (e.g. navigate backwards in time) +- `since_id` (optional): Skip statuses older than ID (e.g. check for updates) + +## Notifications + +**GET /api/v1/notifications** + +Returns notifications for the authenticated user. Each notification has an `id`, a `type` (mention, reblog, favourite, follow), an `account` which it came *from*, and in case of mention, reblog and favourite also a `status`. + +## Following a remote user + +**POST /api/v1/follows** + +Form data: + +- uri: username@domain of the person you want to follow + +Returns the local representation of the followed account. + +## Fetching data + +**GET /api/v1/statuses/:id** + +Returns status. + +**GET /api/v1/accounts/:id** + +Returns account. + +**GET /api/v1/accounts/verify_credentials** + +Returns authenticated user's account. + +**GET /api/v1/accounts/:id/statuses** + +Returns statuses by user. Same options as timeline are permitted. + +**GET /api/v1/accounts/:id/following** + +Returns users the given user is following. + +**GET /api/v1/accounts/:id/followers** + +Returns users the given user is followed by. + +**GET /api/v1/accounts/relationships** + +Returns relationships (`following`, `followed_by`, `blocking`) of the current user to a list of given accounts. + +Query parameters: + +- `id` (can be array): Account IDs + +**GET /api/v1/accounts/search** + +Returns matching accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database. + +Query parameters: + +- `q`: what to search for +- `limit`: maximum number of matching accounts to return + +**GET /api/v1/blocks** + +Returns accounts blocked by authenticated user. + +**GET /api/v1/favourites** + +Returns statuses favourited by authenticated user. + +## Deleting a status + +**DELETE /api/v1/statuses/:id** + +Returns an empty object. + +## Reblogging a status + +**POST /api/v1/statuses/:id/reblog** + +Returns a new status that wraps around the reblogged one. + +## Unreblogging a status + +**POST /api/v1/statuses/:id/unreblog** + +Returns the status that used to be reblogged. + +## Favouriting a status + +**POST /api/v1/statuses/:id/favourite** + +Returns the target status. + +## Unfavouriting a status + +**POST /api/v1/statuses/:id/unfavourite** + +Returns the target status. + +## Threads + +**GET /api/v1/statuses/:id/context** + +Returns `ancestors` and `descendants` of the status. + +## Who reblogged/favourited a status + +**GET /api/v1/statuses/:id/reblogged_by** +**GET /api/v1/statuses/:id/favourited_by** + +Returns list of accounts. + +## Following and unfollowing users + +**POST /api/v1/accounts/:id/follow** +**POST /api/v1/accounts/:id/unfollow** + +Returns the updated relationship to the user. + +## Blocking and unblocking users + +**POST /api/v1/accounts/:id/block** +**POST /api/v1/accounts/:id/unblock** + +Returns the updated relationship to the user. + +## OAuth apps + +**POST /api/v1/apps** + +Form data: + +- `client_name`: Name of your application +- `redirect_uris`: Where the user should be redirected after authorization (for no redirect, use `urn:ietf:wg:oauth:2.0:oob`) +- `scopes`: This can be a space-separated list of the following items: "read", "write" and "follow" (see [this page](OAuth-details.md) for details on what the scopes do) +- `website`: (optional) URL to the homepage of your app + +Creates a new OAuth app. Returns `id`, `client_id` and `client_secret` which can be used with [OAuth authentication in your 3rd party app](Testing-with-cURL.md). + +___ + +# Entities + +## Status + +| Attribute | Description | +|---------------------|-------------| +| `id` || +| `uri` | fediverse-unique resource ID | +| `url` | URL to the status page (can be remote) | +| `account` | Account | +| `in_reply_to_id` | null or ID of status it replies to | +| `reblog` | null or Status| +| `content` | Body of the status. This will contain HTML (remote HTML already sanitized) | +| `created_at` || +| `reblogs_count` || +| `favourites_count` || +| `reblogged` | Boolean for authenticated user | +| `favourited` | Boolean for authenticated user | +| `media_attachments` | array of MediaAttachments | +| `mentions` | array of Mentions | +| `application` | Application from which the status was posted | + +Media Attachment: + +| Attribute | Description | +|---------------------|-------------| +| `url` | URL of the original image (can be remote) | +| `preview_url` | URL of the preview image | +| `type` | Image or video | + +Mention: + +| Attribute | Description | +|---------------------|-------------| +| `url` | URL of user's profile (can be remote) | +| `acct` | Username for local or username@domain for remote users | +| `id` | Account ID | + +Application: + +| Attribute | Description | +|---------------------|-------------| +| `name` | Name of the app | +| `website` | Homepage URL of the app | + +## Account + +| Attribute | Description | +|-------------------|-------------| +| `id` || +| `username` || +| `acct` | Equals username for local users, includes @domain for remote ones | +| `display_name` || +| `note` | Biography of user | +| `url` | URL of the user's profile page (can be remote) | +| `avatar` | URL to the avatar image | +| `header` | URL to the header image | +| `followers_count` || +| `following_count` || +| `statuses_count` || + +# Pagination + +API methods that return collections of items can return a `Link` header containing URLs for the `next` and `prev` pages. [Link header RFC](https://tools.ietf.org/html/rfc5988) -- cgit From 2baf0fabb41e68f1cd4bb60a488aef60cc6ee504 Mon Sep 17 00:00:00 2001 From: Eugen Rochko Date: Sat, 21 Jan 2017 22:53:02 +0100 Subject: Improve API docs formatting --- docs/Using-the-API/API.md | 49 ++++++++++++++------------- docs/Using-the-API/OAuth-details.md | 5 ++- docs/Using-the-API/Testing-with-cURL.md | 3 ++ docs/Using-the-API/Tips-for-app-developers.md | 11 +++--- 4 files changed, 40 insertions(+), 28 deletions(-) (limited to 'docs/Using-the-API/API.md') diff --git a/docs/Using-the-API/API.md b/docs/Using-the-API/API.md index 81225d716..9f5280870 100644 --- a/docs/Using-the-API/API.md +++ b/docs/Using-the-API/API.md @@ -1,4 +1,7 @@ -# Contents +API overview +============ + +## Contents - [Available libraries](#available-libraries) - [Notes](#notes) @@ -22,21 +25,21 @@ - Account - [Pagination](#pagination) -# Available libraries +## Available libraries - [For Ruby](https://github.com/tootsuite/mastodon-api) - [For Python](https://github.com/halcy/Mastodon.py) - [For JavaScript](https://github.com/Zatnosk/libodonjs) - [For JavaScript (Node.js)](https://github.com/jessicahayley/node-mastodon) -# Notes +## Notes When an array parameter is mentioned, the Rails convention of specifying array parameters in query strings is meant. For example, a ruby array like `foo = [1, 2, 3]` can be encoded in the params as `foo[]=1&foo[]=2&foo[]=3`. Square brackets can be indexed but can also be empty. When a file parameter is mentioned, a form-encoded upload is expected. -# Methods -## Posting a new status +## Methods +### Posting a new status **POST /api/v1/statuses** @@ -58,7 +61,7 @@ Form data: Returns a media object with an ID that can be attached when creating a status (see above). -## Retrieving a timeline +### Retrieving a timeline **GET /api/v1/timelines/home** **GET /api/v1/timelines/mentions** @@ -72,13 +75,13 @@ Query parameters: - `max_id` (optional): Skip statuses younger than ID (e.g. navigate backwards in time) - `since_id` (optional): Skip statuses older than ID (e.g. check for updates) -## Notifications +### Notifications **GET /api/v1/notifications** Returns notifications for the authenticated user. Each notification has an `id`, a `type` (mention, reblog, favourite, follow), an `account` which it came *from*, and in case of mention, reblog and favourite also a `status`. -## Following a remote user +### Following a remote user **POST /api/v1/follows** @@ -88,7 +91,7 @@ Form data: Returns the local representation of the followed account. -## Fetching data +### Fetching data **GET /api/v1/statuses/:id** @@ -139,64 +142,64 @@ Returns accounts blocked by authenticated user. Returns statuses favourited by authenticated user. -## Deleting a status +### Deleting a status **DELETE /api/v1/statuses/:id** Returns an empty object. -## Reblogging a status +### Reblogging a status **POST /api/v1/statuses/:id/reblog** Returns a new status that wraps around the reblogged one. -## Unreblogging a status +### Unreblogging a status **POST /api/v1/statuses/:id/unreblog** Returns the status that used to be reblogged. -## Favouriting a status +### Favouriting a status **POST /api/v1/statuses/:id/favourite** Returns the target status. -## Unfavouriting a status +### Unfavouriting a status **POST /api/v1/statuses/:id/unfavourite** Returns the target status. -## Threads +### Threads **GET /api/v1/statuses/:id/context** Returns `ancestors` and `descendants` of the status. -## Who reblogged/favourited a status +### Who reblogged/favourited a status **GET /api/v1/statuses/:id/reblogged_by** **GET /api/v1/statuses/:id/favourited_by** Returns list of accounts. -## Following and unfollowing users +### Following and unfollowing users **POST /api/v1/accounts/:id/follow** **POST /api/v1/accounts/:id/unfollow** Returns the updated relationship to the user. -## Blocking and unblocking users +### Blocking and unblocking users **POST /api/v1/accounts/:id/block** **POST /api/v1/accounts/:id/unblock** Returns the updated relationship to the user. -## OAuth apps +### OAuth apps **POST /api/v1/apps** @@ -211,9 +214,9 @@ Creates a new OAuth app. Returns `id`, `client_id` and `client_secret` which can ___ -# Entities +## Entities -## Status +### Status | Attribute | Description | |---------------------|-------------| @@ -256,7 +259,7 @@ Application: | `name` | Name of the app | | `website` | Homepage URL of the app | -## Account +### Account | Attribute | Description | |-------------------|-------------| @@ -272,6 +275,6 @@ Application: | `following_count` || | `statuses_count` || -# Pagination +## Pagination API methods that return collections of items can return a `Link` header containing URLs for the `next` and `prev` pages. [Link header RFC](https://tools.ietf.org/html/rfc5988) diff --git a/docs/Using-the-API/OAuth-details.md b/docs/Using-the-API/OAuth-details.md index 8e63b89f4..d0b5abd40 100644 --- a/docs/Using-the-API/OAuth-details.md +++ b/docs/Using-the-API/OAuth-details.md @@ -1,3 +1,6 @@ +OAuth details +============= + We use the [Doorkeeper gem for OAuth](https://github.com/doorkeeper-gem/doorkeeper/wiki), so you can refer to their docs on specifics of the end-points. The API is divided up into access scopes: @@ -6,4 +9,4 @@ The API is divided up into access scopes: - `write`: Post statuses and upload media for statuses - `follow`: Follow, unfollow, block, unblock -Multiple scopes can be requested during the authorization phase with the `scope` query param (space-separate the scopes). \ No newline at end of file +Multiple scopes can be requested during the authorization phase with the `scope` query param (space-separate the scopes). diff --git a/docs/Using-the-API/Testing-with-cURL.md b/docs/Using-the-API/Testing-with-cURL.md index f66ccc2b9..977773a08 100644 --- a/docs/Using-the-API/Testing-with-cURL.md +++ b/docs/Using-the-API/Testing-with-cURL.md @@ -1,3 +1,6 @@ +Testing the API with cURL +========================= + Mastodon builds around the idea of being a server first, rather than a client itself. Similarly to how a XMPP chat server communicates with others and with its own clients, Mastodon takes care of federation to other networks, like other Mastodon or GNU Social instances. So Mastodon provides a REST API, and a 3rd-party app system for using it via OAuth2. You can get a client ID and client secret required for OAuth [via an API end-point](API.md#oauth-apps). diff --git a/docs/Using-the-API/Tips-for-app-developers.md b/docs/Using-the-API/Tips-for-app-developers.md index 0cf2a882c..561f1e273 100644 --- a/docs/Using-the-API/Tips-for-app-developers.md +++ b/docs/Using-the-API/Tips-for-app-developers.md @@ -1,13 +1,16 @@ -# Authentication +Tips for app developers +======================= + +## Authentication Make sure that you allow your users to specify the domain they want to connect to before login. Use that domain to acquire a client id/secret for OAuth2 and then proceed with normal OAuth2 also using that domain to build the URLs. In my opinion it is easier for people to understand what is being asked of them if you ask for a `username@domain` type input, since it looks like an e-mail address. Though the username part is not required for anything in the OAuth2 process. Once the user is logged in, you get information about the logged in user from `/api/v1/accounts/verify_credentials` -# Usernames +## Usernames Make sure that you make it possible to see the `acct` of any user in your app (since it includes the domain part for remote users), people must be able to tell apart users from different domains with the same username. -# Formatting +## Formatting -The API delivers already formatted HTML to your app. This isn't ideal since not all apps are based on HTML, but this is not fixable as its part of the way OStatus federation works. Most importantly, you get some information on linked entities alongside the HTML of the status body. For example, you get a list of mentioned users, and a list of media attachments, and a list of hashtags. It is possible to convert the HTML to whatever you need in your app by parsing the HTML tags and matching their `href`s to the linked entities. If a match cannot be found, the link must stay a clickable link. \ No newline at end of file +The API delivers already formatted HTML to your app. This isn't ideal since not all apps are based on HTML, but this is not fixable as its part of the way OStatus federation works. Most importantly, you get some information on linked entities alongside the HTML of the status body. For example, you get a list of mentioned users, and a list of media attachments, and a list of hashtags. It is possible to convert the HTML to whatever you need in your app by parsing the HTML tags and matching their `href`s to the linked entities. If a match cannot be found, the link must stay a clickable link. -- cgit