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 <thematthar...@twitter.com>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

Reply via email to