Matt : I suggest in the "Example Requests" you add the URL for the call. It will prevent much of the "What URL to call?" queries.
--Regards, Denzil On Fri, Jun 24, 2011 at 4:55 AM, Matt Harris <[email protected]>wrote: > 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 > -- 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
