From 9bb398ee9199f786c0c2539601deb2d9416c9d0c Mon Sep 17 00:00:00 2001 From: Ryan Freebern Date: Mon, 10 Apr 2017 07:01:43 -0400 Subject: [PATCH] Minor clarifications (#1386) --- docs/Using-the-API/OAuth-details.md | 2 +- docs/Using-the-API/Testing-with-cURL.md | 4 ++-- docs/Using-the-API/Tips-for-app-developers.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/Using-the-API/OAuth-details.md b/docs/Using-the-API/OAuth-details.md index d0b5abd40b..e88a256826 100644 --- a/docs/Using-the-API/OAuth-details.md +++ b/docs/Using-the-API/OAuth-details.md @@ -9,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). +Multiple scopes can be requested during the authorization phase with the `scope` query param (space-separate the scopes). If you do not specify a `scope` in your authorization request, the resulting access token will default to `read` access. diff --git a/docs/Using-the-API/Testing-with-cURL.md b/docs/Using-the-API/Testing-with-cURL.md index dc5f2022d1..a373ec2bbc 100644 --- a/docs/Using-the-API/Testing-with-cURL.md +++ b/docs/Using-the-API/Testing-with-cURL.md @@ -3,7 +3,7 @@ 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). +You can get a client ID and client secret required for OAuth [via an API end-point](API.md#apps). From these two, you will need to acquire an access token. It is possible to do using your account's e-mail and password like this: @@ -13,6 +13,6 @@ The `/oauth/token` path will attempt to login with the given credentials, and th Use that token in any API requests by setting a header like this: - curl --header "Authorization: Bearer ACCESS_TOKEN_HERE" -sS https://mastodon.social/api/statuses/home + curl --header "Authorization: Bearer ACCESS_TOKEN_HERE" -sS https://mastodon.social/api/v1/timelines/home Please note that the password-based approach is not recommended especially if you're dealing with other user's accounts and not just your own. Usually you would use the authorization grant approach where you redirect the user to a web page on the original site where they can login and authorize the application and are then redirected back to your application with an access code. diff --git a/docs/Using-the-API/Tips-for-app-developers.md b/docs/Using-the-API/Tips-for-app-developers.md index 561f1e2737..d60b472e58 100644 --- a/docs/Using-the-API/Tips-for-app-developers.md +++ b/docs/Using-the-API/Tips-for-app-developers.md @@ -13,4 +13,4 @@ Make sure that you make it possible to see the `acct` of any user in your app (s ## 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 it's 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.