Re: [twitter-dev] Poor documentation. For example, regarding lists. Suggestions for improvement.
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.comwrote:
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=cnnslug=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=cnnslug=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,
@themattharrishttps://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
Re: [twitter-dev] Poor documentation. For example, regarding lists. Suggestions for improvement.
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.comwrote:
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=cnnslug=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=cnnslug=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,
@themattharrishttps://twitter.com/intent/follow?screen_name=themattharris
Developer Advocate, Twitter
--
Twitter developer
Re: [twitter-dev] Poor documentation. For example, regarding lists. Suggestions for improvement.
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=cnnslug=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=cnnslug=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-dev] Poor documentation. For example, regarding lists. Suggestions for improvement.
I'm using this call for my website.
http://dev.twitter.com/doc/get/lists/statuses
The documentation states that the url works like this:
http://api.twitter.com/**version**/lists/statuses.**format**
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.
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=cnnslug=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.
Issue #3: No obvious way to discover list_id or owner_id
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.
For issues 2 though 4, a single, helpful example url would have done
wonders. If the API put http://api.twitter.com/1/cnn/lists/cnnnews/statuses.json
on the page it would have saved me about 5 hours of work.
--
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
