Hi Denzil, Thanks for the suggestion. Do you think that would help or would it be better to try and link to the console? Just curious about alternative ideas.
The reason I say this is POST and DELETE requests are difficult to write as single example URLs. When we had them in the past they led to confusion with OAuth signing. Best, @themattharris <https://twitter.com/intent/follow?screen_name=themattharris> Developer Advocate, Twitter On Fri, Jun 24, 2011 at 1:42 AM, Correa Denzil <[email protected]> wrote: > 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 > -- 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
