Hi Dave,
Thanks for your feedback, it's important for us to know when developers are
not finding the information they are looking for.
I have responded to your specific points inline:
> Issue #1: Valid version numbers
>
> I was unable to locate valid values for "version". I tried 1.1.14,
> which I understand the current version to be from searching the site,
> but that causes a 404. It was only after digging around for examples
> that I noticed people using "1". A page describing valid version
> numbers should be linked from the word "version".
>
In the API documentation there is a version place marker in the example
request URL. Currently only one version of the API exists, that version is
1. This means any REST API queries will be of the format:
https://api.twitter.com/1/statuses/user_timeline.json
I've updated the "API FAQ" and "Things Every Developer Should Know" pages to
include this information.
http://dev.twitter.com/pages/every_developer
https://dev.twitter.com/pages/api_faq
Issue #2: Extremely unclear parameter passing
>
> As this call uses GET, and the documentation lists parameters you
> should include, this implies to me that you should use a query string.
> The docs list the following required parameters:
>
> * list_id - The numerical id of the list.
> * slug - You can identify a list by its slug instead of its numerical
> id. If you decide to do so, note that you'll also have to specify the
> list owner using the owner_id or owner_screen_name parameters.
>
> As it is not at all obvious how you discover the "list_id" or
> "owner_id", I opted to use "slug" and "owner_screen_name". However, if
> you
>
> $ curl
> http://api.twitter.com/1/lists/statuses.json?owner_screen_name=cnn&slug=cnnnews
>
> you get
>
> {"error":"You must specify either a list ID or a slug and
> owner","request":"\/1\/lists\/statuses.json?owner_screen_name=cnn"}
>
> Notice that the response json lists the request with only the
> "owner_screen_name" parameter. I imagine that 1 or more things went
> wrong, possibly including:
>
> 1. The API has a bug that is stripping the second parameter
> 2. The documentation is incorrect, and you may not use "slug" and
> "owner_screen_name" to retrieve results.
> 3. The documentation does not properly describe how you pass the
> arguments in the query string. Perhaps you're supposed to encode the
> entire string. I was not able to discern this.
> 4. The documentation is incorrect about the url format.
>
The request you are making is correct. The error is instead being caused by
the way in which you are using your terminal. When using a terminal like
this you need to remember to either quote your URL or escape the &'s.
This would make your request look like this:
curl "
http://api.twitter.com/1/lists/statuses.json?owner_screen_name=cnn&slug=cnnnews
"
> Issue #3: No obvious way to discover "list_id" or "owner_id"
>
user_ids are provided in all API responses which include a user object. The
most common way of getting information about a user is through the
users/show method or users/lookup method:
http://dev.twitter.com/doc/get/users/show
http://dev.twitter.com/doc/get/users/lookup
list_id is available from the index of lists for a user. This request is the
/1/lists request:
http://dev.twitter.com/doc/get/lists
Alternatively, if those values are unknown or you don't wish to look them
up, you can provide the slug and screen_name as you have done in your
example.
> Issue #4: Undocumented, un-obvious correct url
>
> I was finally able to retrieve the results using this url, pieced
> together from scattered examples.
>
> $ curl http://api.twitter.com/1/cnn/lists/cnnnews/statuses.json
> So far as I could tell, the documentation in no way implies that you
> could use such a url.
>
This is the deprecated way of making lists requests. It is documented on
this page of the developer resources site:
http://dev.twitter.com/doc/get/:user/lists/:id/statuses
I hope that helps explain a little bit more about the API. Let me know if
this information is useful or what you would change and we'll see how we can
incorporate it into the docs.
Best,
@themattharris <https://twitter.com/intent/follow?screen_name=themattharris>
Developer Advocate, Twitter
--
Twitter developer documentation and resources: https://dev.twitter.com/doc
API updates via Twitter: https://twitter.com/twitterapi
Issues/Enhancements Tracker: https://code.google.com/p/twitter-api/issues/list
Change your membership to this group:
https://groups.google.com/forum/#!forum/twitter-development-talk
