Please add examples and more explanation to the API documentation

[ghost]

I'm not sure if it's okay to ask for this, but it's pretty hard to figure out how to use the API properly >_<;

For example, several endpoints mention to get max_id and since_id from something called a "link header". (for example https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#getting-who-account-is-following). The only explanation of what a "link header" is is at the top of the page as a link to an RFC. A simple example would explain things much quicker and simpler than pointing to an abstract and complex design document.

Another example, it's mentioned at the top of the page that a file needs to be "form-encoded". But later on, https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#updating-the-current-user says that images need to be "base64 encoded". So, which is it? Are they different? How to accomplish these encodings? An example of an API call that accomplishes the thing properly would be much easier to understand than describing it in words.

Some other things that aren't explained:

• what the length/size limits are for various text fields and file uploads
• what happens when these limits are exceeded
• what a "card" is (https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#getting-a-card-associated-with-a-status)
• what the URL for a hashtag is (https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#tag).

[Gargron]

Another example, it's mentioned at the top of the page that a file needs to be "form-encoded". But later on, https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#updating-the-current-user says that images need to be "base64 encoded". So, which is it? Are they different? How to accomplish these encodings?

Both are accepted in both cases actually, but that base64 bit was submitted by an outside contributor, it'd be nice to have some consistency there.

[ghost]

To answer one of my questions, a "card" is one of those preview thingies that are shown for links to some official/commercial sites.

And to add some more questions,

• is it correct that statuses/id/context doesn't have the since_id / max_id / limit thing? It's kinda surprising since most other endpoints that return lists have it, and this one could give some pretty long lists too. (https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#getting-status-context)
• the endpoints for follow requests are said to have an id parameter, but that id is already in the resource url. Is it necessary to give it twice or is that a mistake? (https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#authorizing-or-rejecting-follow-requests)
• domain blocks aren't documented yet? I don't know if there are endpoints for them, but at least https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#relationship should list the included domain_blocking field

[Gargron]

is it correct that statuses/id/context doesn't have the since_id / max_id / limit thing? It's kinda surprising since most other endpoints that return lists have it, and this one could give some pretty long lists too. (https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#getting-status-context)

Yes, correct. It's a tree view so it's difficult to paginate, easier to just return all results

he endpoints for follow requests are said to have an id parameter, but that id is already in the resource url. Is it necessary to give it twice or is that a mistake? (https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#authorizing-or-rejecting-follow-requests)

Mistake

domain blocks aren't documented yet? I don't know if there are endpoints for them, but at least https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#relationship should list the included domain_blocking field

I actually added documentation for that recently!

[ghost]

Ah, I should've reloaded the tab before asking about it ^_^; Thanks for the quick updates.

Still hoping for an example of the since_id / max_id thing. I've figured out how to get that Link: header from curl, but I don't get how they're used. The max_id / rel="next" one seems to go forward in the list, the other only jumps back to the beginning? I'm probably doing something worng >_<;

The IDs also don't seem to correspond for the accounts/id/following endpoint (probably others too, but this was the one I was trying out just now). max_id and since_id have completely different values than the IDs of the user accounts that are returned.

And maybe I should report this over on the main source github as a bug, but is it correct that I'm getting an error "This action is outside the authorized scopes" when trying to get a list of blocked accounts through the blocks endpoint with an app that has read & write scope (but not follow)? I'd expect read scope alone to be enough to use all the GET endpoints at least. In order to display toots properly you need to know what to not display, isn't it?

[ornithocoder]

If you want to build an application (and not a library), I recommend you to pick a library that wraps the Mastodon API other developers already implemented. You can find the list here.

[ornithocoder]

Still hoping for an example of the since_id / max_id thing. I've figured out how to get that Link: header from curl, but I don't get how they're used. The max_id / rel="next" one seems to go forward in the list, the other only jumps back to the beginning? I'm probably doing something worng >_<;

max_id and since_id are used to limit the query results. One sets the ceiling result while the other the floor.

The IDs also don't seem to correspond for the accounts/id/following endpoint (probably others too, but this was the one I was trying out just now). max_id and since_id have completely different values than the IDs of the user accounts that are returned.

The ID depends on the endpoint. For a timeline (status array), the id is the status id. For and endpoint that returns an account array, it's the account id.

And maybe I should report this over on the main source github as a bug, but is it correct that I'm getting an error "This action is outside the authorized scopes" when trying to get a list of blocked accounts through the blocks endpoint with an app that has read & write scope (but not follow)?

public enum AccessScope {
    /// Allows reading data.
    case read
    /// Allows posting statuses and uploading media for statuses.
    case write
    /// Allows following, unfollowing, blocking, and unblocking users.
    case follow
}

In order to display toots properly you need to know what to not display, isn't it?

Read access gives access to toots. Follow access isn't necessary for that.

[ghost]

So it is a bug then to get that error accessing the blocks endpoint? I'm not trying to block an account, only to get a list of blocked accounts (https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#blocks)

As for the library thing, yah, but my language of choice is Lua. There is a lua-mastodon library, but it can't even upload media because the library it depends on for http communication doesn't do uploads. So I'm reinventing that wheel for myself ^_^; The lua-curl library looked super complicated, so for now I'm just using commandline curl.

Re: IDs, the accounts/id/followers endpoint just now returned accounts with IDs 6393 and 10881 (using limit=2 to not flood my screen), and the Link: header suggested a since_id of 63369 and a max_id of 62490. They don't seem to be related at all :/

[Gargron]

Re: IDs, the accounts/id/followers endpoint just now returned accounts with IDs 6393 and 10881 (using limit=2 to not flood my screen), and the Link: header suggested a since_id of 63369 and a max_id of 62490. They don't seem to be related at all :/

Yes, they're not related. You should use the values from the Link header.

[ghost]

Okay, that was my guess, but the API documentation suggests that they are related, apparently even confusing @ornithocoder above.

That leaves the pagination not going back and forth quite right. The link that says max_id=something and rel="next" works to get the next 'page' of results, but the other link (since_id=somethingelse and rel="prev") doesn't go back to the previous 'page' of results and instead gives the first 'page' of results again. Am I doing it worng?

[dariusk]

This is great feedback, @kimik0! Exactly the kind of thing that will make the docs better in the future. I'm going to take all this into consideration and see if I can do a documentation pass to clarify all these.

[ghost]

Thanks. I'm glad my questions are useful. And it's pretty cool to be talking to celebs like Gargron and DariusK *^_^*

Ah, one more. What is the point of the notifications/id endpoint if the only way to find that id is from the notification itself? I mean, I'd need to already have the notification in order to get it.. o_0
(https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md#getting-a-single-notification)

[ghost]

Now getting into the actual data (instead of only fetching it).

Is there a reason for urls of remote toots being formatted differently than urls of local toots?
For a local toot, the url looks like "https:/ /instance.domain/@ username/tootid"
For a remote toot, the url instead looks like "https:/ /instance.domain/users/username/updates/someotherid" (where someotherid matches neither the local toot id nor the remote toot id)
The toot's proper id is available as part of the uri, so why not use the more readable format?
For example, https://botsin.space/users/emojispells/updates/75494 can be converted to https://botsin.space/@emojispells/154040 . Same toot, different url.
FWIW, both variants give the same results when passed as a search query to my local instance (same url (the second, less nice variant), same uri, same (local) id). Adding resolve=true to the query didn't make a difference in either case.
And passed to the remote instance (no authentication required for searches), both also give the same results, except then I get the nicer looking url variant returned and the toot's remote id.

Is a toot's spoiler_text also in HTML, like the content? And what does it mean that "remote HTML" is "already sanitized"? Does that only replace the character entities? Is there some standard string replacement done to turn a toot from plain text (as it is typed or sent) into HTML (which can then be undone by the reverse replacement), or do I need to look into full HTML parsing to turn toots back into plain text?

The meta field of attachments is not properly documented. It's not a table of width, height, size, aspect, but a table of small and original which are then tables of the width etc. I think it would be better to split the description of this meta information into separate entries in the documentation.

Formatting consistency nitpick: types of attachments, cards and notifications are listed as "string"s, but visibility of toots is listed as strings.

[wxcafe]

I believe since that issues was opened the docs have improved in some matters? @kimik0 please review whether that issue should still be open.