Difference between revisions of "YTMND:API:Basic Overview"

From YTMND
Jump to: navigation, search
m
(Terminology)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== YTMND Developer API: Basic Overview ==
 
== YTMND Developer API: Basic Overview ==
  
 +
== Terminology ==
  
<small>This documentation is partially plagiarized from the [http://apidoc.digg.com/ Digg API] documentation, as the YTMND API was modeled after it.</small>
+
*'''Interface'''
 +
Interfaces are groupings of methods specific to an area of data, at the time of writing this the available interfaces are "sites" and "users".
 +
 
 +
*'''Method'''
 +
Methods are a set of functions that can be applied to an interface to return specific data.  
 +
 
 +
*'''Method Group'''
 +
Method Groups are a predefined set of methods which group together multiple methods to provide commonly requested data.
 +
 
 +
*'''Response Format'''
 +
The literal format of the data returned by the API which can be specified remotely.
  
 
== Requests ==
 
== Requests ==
  
 +
All YTMND API requests use a [http://en.wikipedia.org/wiki/REST REST] format in a fairly flexible way. (Currently in it's beta phase, the URL format is close to being finalized but some of this information may become less accurate over the next month.)
  
* See [[YTMND:API:Response Formats|Response Formats]] for details on specifying the desired format you would like returned
+
URLs are comprised of at least one of each of the following:
* 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 [http://developer.yahoo.com/javascript/howto-proxy.html proxied] to avoid [http://en.wikipedia.org/wiki/Same_origin_policy same-origin policy] conflicts.
+
  
 +
*One interface.
 +
*One or more methods or method groups.
 +
*One or more items to look up (such as a user name, user_id, domain or site_id)
  
 +
There are multiple methods of providing each piece of information required, you are free to use them as you see fit. For instance, these URLs all point to the same interface:
  
== Responses ==
+
http://api.ytmnd.com/site/1
 +
http://api.ytmnd.com/sites/1/
 +
http://api.ytmnd.com/?interface=sites&site_id=1.
  
 +
Methods can be sent in the following ways:
  
* All responses are UTF-8 encoded, the default response format is XML.
+
http://api.ytmnd.com/sites/1/assets+score
* Times are expressed in [http://en.wikipedia.org/wiki/Unix_timestamp Unix epoch timestamp] format.
+
http://api.ytmnd.com/?interface=sites&site_id=1&method=assets+score
:* 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.
+
For the sites interface, the valid item variables are "site_id" and "domain", for users; "user_id" or "user_name":
::It is possible that in the future an option may be added to allow timestamps to be returned in CST.
+
 
 +
http://api.ytmnd.com/sites/?site_id=1 is the same as http://api.ytmnd.com/sites/1
 +
http://api.ytmnd.com/users/?user_id=1 is the same as http://api.ytmnd.com/users/1
 +
 
 +
There are also a few ways of passing multiple items in
 +
 
 +
http://api.ytmnd.com/sites/1,10/assets
 +
http://api.ytmnd.com/sites/?site_id=1,10&method=assets
 +
<nowiki>http://api.ytmnd.com/sites/?site_id[]=1&site_id[]=10&method=assets  (this allows you to post GET requests directly from HTML forms using HTML arrays)</nowiki>
 +
 
 +
The same can be done with user names and domains:
 +
 
 +
http://api.ytmnd.com/sites/yourethemannowdog,babyruth/assets etc.
 +
 
 +
It should be noted that requests to the sites and user interfaces have to do an extra lookup if you pass in domains and user names respectively. When possible, you will be able to shave off some milliseconds from your request by using id numbers in subsequent requests or when available.
 +
 
 +
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 ==
  
 +
*See [[YTMND:API:Response Formats|Response Formats]] for details on specifying the desired format you would like returned.
 +
*All responses are UTF-8 encoded, the default response format is XML.
 +
*Dates and Times are expressed in [http://en.wikipedia.org/wiki/ISO_8601 ISO_8601] format by default in XML.
 +
Currently there is some debate as to what the default format should be for other request types, discussion can be made on the [http://wiki.ytmnd.com/YTMND_talk:API main API] talk page.
  
* 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.
+
*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 (see [http://wiki.ytmnd.com/YTMND:API:Interfaces interface pages] for more information).
* 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 at some point receive a response code of 403 (Forbidden) in a case that we feel you are hitting our server too rapidly. (this is currently unimplemented)
:* More information can be found in the [[YTMND:API:Error and Response Codes|Error and Response Codes]] and [[YTMND:API:Restrictions|Restrictions and Limitations]] articles.
+
*More information can be found in the [[YTMND:API:Error and Response Codes|Error and Response Codes]] article.
  
  
Line 33: Line 73:
  
  
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. The API is written in PHP which doesn't handle memory limits well. Hitting the memory limit in PHP is a fatal error and can not currently be encapsulated in an error handler, this means if you hit a memory limit you will get a PHP error in plain-text rather than an actual API error. Rather than setting the memory limit to something ludicrous, we opted to set it high (64MB) and pay attention to the methods that could be hitting that limit in hopes of trimming down areas that use more memory than it should. Currently it is basically impossible to hit memory limits making requests on single items.
  
  

Latest revision as of 18:30, October 31, 2007

YTMND Developer API: Basic Overview

Terminology

  • Interface

Interfaces are groupings of methods specific to an area of data, at the time of writing this the available interfaces are "sites" and "users".

  • Method

Methods are a set of functions that can be applied to an interface to return specific data.

  • Method Group

Method Groups are a predefined set of methods which group together multiple methods to provide commonly requested data.

  • Response Format

The literal format of the data returned by the API which can be specified remotely.

Requests

All YTMND API requests use a REST format in a fairly flexible way. (Currently in it's beta phase, the URL format is close to being finalized but some of this information may become less accurate over the next month.)

URLs are comprised of at least one of each of the following:

  • One interface.
  • One or more methods or method groups.
  • One or more items to look up (such as a user name, user_id, domain or site_id)

There are multiple methods of providing each piece of information required, you are free to use them as you see fit. For instance, these URLs all point to the same interface:

http://api.ytmnd.com/site/1
http://api.ytmnd.com/sites/1/
http://api.ytmnd.com/?interface=sites&site_id=1.

Methods can be sent in the following ways:

http://api.ytmnd.com/sites/1/assets+score
http://api.ytmnd.com/?interface=sites&site_id=1&method=assets+score

For the sites interface, the valid item variables are "site_id" and "domain", for users; "user_id" or "user_name":

http://api.ytmnd.com/sites/?site_id=1 is the same as http://api.ytmnd.com/sites/1
http://api.ytmnd.com/users/?user_id=1 is the same as http://api.ytmnd.com/users/1

There are also a few ways of passing multiple items in

http://api.ytmnd.com/sites/1,10/assets
http://api.ytmnd.com/sites/?site_id=1,10&method=assets 
http://api.ytmnd.com/sites/?site_id[]=1&site_id[]=10&method=assets  (this allows you to post GET requests directly from HTML forms using HTML arrays)

The same can be done with user names and domains:

http://api.ytmnd.com/sites/yourethemannowdog,babyruth/assets etc.

It should be noted that requests to the sites and user interfaces have to do an extra lookup if you pass in domains and user names respectively. When possible, you will be able to shave off some milliseconds from your request by using id numbers in subsequent requests or when available.

Requests made from Javascript running on your web pages should be proxied to avoid same-origin policy conflicts.


Responses

  • See Response Formats for details on specifying the desired format you would like returned.
  • All responses are UTF-8 encoded, the default response format is XML.
  • Dates and Times are expressed in ISO_8601 format by default in XML.
Currently there is some debate as to what the default format should be for other request types, discussion can be made on the main API talk page.
  • The YTMND API and Digg API differ in that the YTMND API will always return a container, even if your request returns no results (see interface pages for more information).
  • HTTP response codes should always be 200 (OK) or 304 (Not Modified) if the response is cached.
  • You may at some point receive a response code of 403 (Forbidden) in a case that we feel you are hitting our server too rapidly. (this is currently unimplemented)
  • More information can be found in the Error and Response Codes article.


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. The API is written in PHP which doesn't handle memory limits well. Hitting the memory limit in PHP is a fatal error and can not currently be encapsulated in an error handler, this means if you hit a memory limit you will get a PHP error in plain-text rather than an actual API error. Rather than setting the memory limit to something ludicrous, we opted to set it high (64MB) and pay attention to the methods that could be hitting that limit in hopes of trimming down areas that use more memory than it should. Currently it is basically impossible to hit memory limits making requests on single items.


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. Currently this issue is unimportant, but eventually limitations may be created.