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 <mcen...@gmail.com> 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 <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
>

-- 
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