Difference between revisions of "YTMND:API:Basic Overview"
From YTMND
(→YTMND Developer API: Basic Overview) |
(initial draft) |
||
| Line 4: | Line 4: | ||
<small>This documentation is partially plagiarized from the [http://apidoc.digg.com/ Digg API] documentation, as the YTMND API was modeled after it.</small> | <small>This documentation is partially plagiarized from the [http://apidoc.digg.com/ Digg API] documentation, as the YTMND API was modeled after it.</small> | ||
| + | == Requests == | ||
| − | |||
| − | + | * See [[YTMND:API:Response Formats|Response Formats]] for details on specifying the desired format you would like returned | |
| − | * See | + | * All requests should include a User-Agent HTTP Header and an HTTP Referrer. |
| − | * All requests should include a User-Agent HTTP Header | + | :* This is optional purely for our own statistics. |
* Requests made from Javascript running on your web pages should be [http://developer.yahoo.com/javascript/howto-proxy.html proxied] to avoid [http://en.wikipedia.org/wiki/Same_origin_policy same-origin policy] conflicts. | * Requests made from Javascript running on your web pages should be [http://developer.yahoo.com/javascript/howto-proxy.html proxied] to avoid [http://en.wikipedia.org/wiki/Same_origin_policy same-origin policy] conflicts. | ||
| − | = Responses = | + | == Responses == |
| Line 24: | Line 24: | ||
| − | * The YTMND API and Digg API differ in that the YTMND API will always return a container, even if your request returns no results. | + | * The YTMND API and [http://apidoc.digg.com/ Digg API] differ in that the YTMND API will always return a container, even if your request returns no results. |
* HTTP response codes should always be 200 (OK) or 304 (Not Modified) if the response is cached. | * HTTP response codes should always be 200 (OK) or 304 (Not Modified) if the response is cached. | ||
:* You may receive a response code of 403 (Forbidden) in a case that we feel you are hitting our server too rapidly. | :* You may receive a response code of 403 (Forbidden) in a case that we feel you are hitting our server too rapidly. | ||
| Line 30: | Line 30: | ||
| − | = Data Limitations = | + | == Data Limitations == |
In its initial form, the YTMND API offers no form of pagination or custom limiting of its data response. Each interface has its own specific rules, but in most cases your requests will not return gigantic amounts of data. Various methods should be expected to return more data than others, but such information is listed on each interface's documentation page. | In its initial form, the YTMND API offers no form of pagination or custom limiting of its data response. Each interface has its own specific rules, but in most cases your requests will not return gigantic amounts of data. Various methods should be expected to return more data than others, but such information is listed on each interface's documentation page. | ||
| + | |||
| + | |||
| + | == Caching == | ||
| + | |||
| + | In rare cases when a piece of information is continually requested it may be cached in memory (server-side) for a short period of time to ensure requests don't overload the server. In most cases data is not cached at all. This means that it is up to you to cache when necessary. Setting up a [http://en.wikipedia.org/wiki/Proxy_cache proxy cache] isn't too hard, so please cache your results if you plan on using the API on a high traffic site. We monitor connections to the API and you may get throttled or banned if you request too much data too rapidly. More information can be seen at [[YTMND:API:Restrictions|Restrictions and Limitations]]. | ||
Revision as of 22:53, June 20, 2007
YTMND Developer API: Basic Overview
This documentation is partially plagiarized from the Digg API documentation, as the YTMND API was modeled after it.
Requests
- See Response Formats for details on specifying the desired format you would like returned
- All requests should include a User-Agent HTTP Header and an HTTP Referrer.
- This is optional purely for our own statistics.
- Requests made from Javascript running on your web pages should be proxied to avoid same-origin policy conflicts.
Responses
- All responses are UTF-8 encoded, the default response format is XML.
- Times are expressed in Unix epoch timestamp format.
- All Times are converted to the GMT timezone before being returned.
- This may be problematic as YTMND uses CST for all of its timestamps as its servers are located in the CST timezone.
- It is possible that in the future an option may be added to allow timestamps to be returned in CST.
- The YTMND API and Digg API differ in that the YTMND API will always return a container, even if your request returns no results.
- HTTP response codes should always be 200 (OK) or 304 (Not Modified) if the response is cached.
- You may receive a response code of 403 (Forbidden) in a case that we feel you are hitting our server too rapidly.
- More information can be found in the Error and Response Codes and Restrictions and Limitations articles.
Data Limitations
In its initial form, the YTMND API offers no form of pagination or custom limiting of its data response. Each interface has its own specific rules, but in most cases your requests will not return gigantic amounts of data. Various methods should be expected to return more data than others, but such information is listed on each interface's documentation page.
Caching
In rare cases when a piece of information is continually requested it may be cached in memory (server-side) for a short period of time to ensure requests don't overload the server. In most cases data is not cached at all. This means that it is up to you to cache when necessary. Setting up a proxy cache isn't too hard, so please cache your results if you plan on using the API on a high traffic site. We monitor connections to the API and you may get throttled or banned if you request too much data too rapidly. More information can be seen at Restrictions and Limitations.
