Hot answers tagged documentation
3
Well technically it already says "Most methods" so it's correct as written.
But I agree, it's easy to miss that note. After the next build there will be another sentence mentioning that some methods have lower limits and their individual documentation pages will call them out (as they already do). Should be harder to miss that way.
2
Technically that's incorrect.
The help docs say nothing about the required/optional nature of user and owner, only whether certain of their subfields are required should they be present. This is a gap in our automagic doc generation system which will - eventually - be fixed.
When it is, user and owner will be marked "optional."
2
Returned parameters now have an optional field in the documentation (example) that indicates whether they should always be present.
For the duration of the beta at least (not going to guarantee 1.0+, there are some performance implications) we're actually enforcing this. If a response we're to somehow not have a required field set, an error will occur ...
2
Take a look at http://api.stackoverflow.com/1.1/usage/enumerations ; which is now linked from the front page of the documentation as well.
Its very simplistic, but one of the nice behind the scenes changes in 1.1 was making it a lot easier for me to update the documentation. Expect some better documentation on returned values in the not incredibly distance ...
2
key is your app key, access_token identifies a user (and a set of permissions) and is what you get at the end of an authentication flow.
Keys are not secret, for example here's what the Documentation Console's registration looks like:
You can find your app key by going to Manage Your Applications (in the Stack Apps homepage sidebar) and selecting one of ...
2
Quoting the very first paragraph in the section General:
Applications should be registered on Stack Apps to get a request key. Request keys grant more requests per day, and are necessary for using access_tokens created via authentication.
Click the first link, and there's the registration form.
2
This was dropped intentionally.
The problem is that maintaining this sort of meta-api is both intensive (lots of v1.1 was spent not breaking v1.0 because of the way introspection was working) and of very little utility.
Yes, it's useful for generating wrappers; but those wrappers are written once per version, and not updated meaningfully. If we were ...
1
Kevin was nice enough to grant my recent feature request on this endpoint, so it now returns "paged" results instead of a static top 30. I'm guessing the documentation just wasn't updated to reflect the change.
I've tested it (StinkingBadges is using this functionality) and can confirm that your test result is the current "correct" behavior.
1
status-completed... sort of. I'm still planning on putting something fancy on /docs/types (there's nothing there now) but haven't quite worked out what yet.
Anyhoo, the main /docs page now has tabs
which change how methods are grouped.
"by category" returns methods as they always have been (by site / non-site, then by "what you're thinking about" ...
1
OK, I've just discovered that at the bottom of each "type" page, there's a list with this information. For example: https://api.stackexchange.com/docs/types/user#methods This is insanely useful. But it's in a hard-to-find location, especially since there isn't a comprehensive list of types anywhere.
1
Woops, missed that one.
The /posts/{id}/comment documentation isn't missing, but it is under the Comments header which may make it easy to miss.
Returning "1.0" for the API version is status-bydesign, for compatibility purposes.
It was a mistake to even add that field (made sense in the beta, makes no sense with a released API), consider it deprecated.
1
Commercial use of the API is permitted.
If you're just displaying content on a website, you should follow our attribution requirements. If you have questions about a more specific use case, feel free to contact us.
Only top voted, non community-wiki answers of a minimum length are eligible
