ar
/
mastodon
forked from treehouse/mastodon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve API docs formatting

rebase/4.0.0rc2
Eugen Rochko 2017-01-21 22:53:02 +01:00
parent e92a1cf436
commit 2baf0fabb4
4 changed files with 40 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
docs/Using-the-API/API.md
View File

@ -1,4 +1,7 @@
# Contents API overview
============
## Contents
- [Available libraries](#available-libraries) - [Available libraries](#available-libraries)
- [Notes](#notes) - [Notes](#notes)
@ -22,21 +25,21 @@
- Account - Account
- [Pagination](#pagination) - [Pagination](#pagination)
# Available libraries ## Available libraries
- [For Ruby](https://github.com/tootsuite/mastodon-api) - [For Ruby](https://github.com/tootsuite/mastodon-api)
- [For Python](https://github.com/halcy/Mastodon.py) - [For Python](https://github.com/halcy/Mastodon.py)
- [For JavaScript](https://github.com/Zatnosk/libodonjs) - [For JavaScript](https://github.com/Zatnosk/libodonjs)
- [For JavaScript (Node.js)](https://github.com/jessicahayley/node-mastodon) - [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 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. When a file parameter is mentioned, a form-encoded upload is expected.
# Methods ## Methods
## Posting a new status ### Posting a new status
**POST /api/v1/statuses** **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). 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/home**
**GET /api/v1/timelines/mentions** **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) - `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) - `since_id` (optional): Skip statuses older than ID (e.g. check for updates)
## Notifications ### Notifications
**GET /api/v1/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`. 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** **POST /api/v1/follows**
@ -88,7 +91,7 @@ Form data:
Returns the local representation of the followed account. Returns the local representation of the followed account.
## Fetching data ### Fetching data
**GET /api/v1/statuses/:id** **GET /api/v1/statuses/:id**
@ -139,64 +142,64 @@ Returns accounts blocked by authenticated user.
Returns statuses favourited by authenticated user. Returns statuses favourited by authenticated user.
## Deleting a status ### Deleting a status
**DELETE /api/v1/statuses/:id** **DELETE /api/v1/statuses/:id**
Returns an empty object. Returns an empty object.
## Reblogging a status ### Reblogging a status
**POST /api/v1/statuses/:id/reblog** **POST /api/v1/statuses/:id/reblog**
Returns a new status that wraps around the reblogged one. Returns a new status that wraps around the reblogged one.
## Unreblogging a status ### Unreblogging a status
**POST /api/v1/statuses/:id/unreblog** **POST /api/v1/statuses/:id/unreblog**
Returns the status that used to be reblogged. Returns the status that used to be reblogged.
## Favouriting a status ### Favouriting a status
**POST /api/v1/statuses/:id/favourite** **POST /api/v1/statuses/:id/favourite**
Returns the target status. Returns the target status.
## Unfavouriting a status ### Unfavouriting a status
**POST /api/v1/statuses/:id/unfavourite** **POST /api/v1/statuses/:id/unfavourite**
Returns the target status. Returns the target status.
## Threads ### Threads
**GET /api/v1/statuses/:id/context** **GET /api/v1/statuses/:id/context**
Returns `ancestors` and `descendants` of the status. 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/reblogged_by**
**GET /api/v1/statuses/:id/favourited_by** **GET /api/v1/statuses/:id/favourited_by**
Returns list of accounts. Returns list of accounts.
## Following and unfollowing users ### Following and unfollowing users
**POST /api/v1/accounts/:id/follow** **POST /api/v1/accounts/:id/follow**
**POST /api/v1/accounts/:id/unfollow** **POST /api/v1/accounts/:id/unfollow**
Returns the updated relationship to the user. 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/block**
**POST /api/v1/accounts/:id/unblock** **POST /api/v1/accounts/:id/unblock**
Returns the updated relationship to the user. Returns the updated relationship to the user.
## OAuth apps ### OAuth apps
**POST /api/v1/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 | | Attribute | Description |
|---------------------|-------------| |---------------------|-------------|
@ -256,7 +259,7 @@ Application:
| `name` | Name of the app | | `name` | Name of the app |
| `website` | Homepage URL of the app | | `website` | Homepage URL of the app |
## Account ### Account
| Attribute | Description | | Attribute | Description |
|-------------------|-------------| |-------------------|-------------|
@ -272,6 +275,6 @@ Application:
| `following_count` || | `following_count` ||
| `statuses_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) 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)

3
docs/Using-the-API/OAuth-details.md
View File

@ -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. 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: The API is divided up into access scopes:

3
docs/Using-the-API/Testing-with-cURL.md
View File

@ -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. 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). You can get a client ID and client secret required for OAuth [via an API end-point](API.md#oauth-apps).

9
docs/Using-the-API/Tips-for-app-developers.md
View File

@ -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. 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` 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. 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. 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.