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

Revision as of 21:35, October 21, 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.