API discovery

Where do I start?
So you're writing a client application using StatusNet's API; good for you! Unfortunately the down side of a federated system like ours is that you might need to work with many different StatusNet sites on different domains, with different configuration... maybe even multiple sites used by the same user! So you can't just hardcode a single API endpoint URL into your software like you can for certain monolithic services...

The good news is that StatusNet's API wants to help you find it... but you need to know what you're looking for, and when's the right time to go looking for it.

Scenarios
Once at account setup time:
 * 
 * If you have just a hostname or URL to the site ("identi.ca", "http://example.com/mublog")) and need the actual API URL, you can do discovery from the web page. Once you have this, it should remain stable so is safe to keep as a permanent account option.

Might want to check each session:
 * 
 * Server configuration options like the maximum notice length could change from time to time, so should be refreshed at least once per session. You should be able to continue working if you weren't able to find or update some of this information though, using default or old values.

Finding the API root
As of StatusNet 0.9.2 (plus or minus), the base URL for the Twitter-compatible API can be obtained using Really Simple Discovery. This is the same API discovery system that other tools like WordPress provide for blogging/microblogging protocol discovery:

First, find the  in the site's home page:



Pull that URL down and you'll get something kinda like this:

   StatusNet http://status.net/  http://status.net/wiki/TwitterCompatibleAPI true

Approximate path/selector: /rsd/service/apis/api[@name="Twitter"]/@apiLink

Getting server info

 * statusnet/config. 
 * Formats: xml, json
 * Sample: http://identi.ca/api/statusnet/config.xml

This can provide very useful info about the server, the most important of which for a client is likely:
 * Max character count: config/site/textlimit

You can also find various useful info such as whether the site is marked as public or private, which may help in deciding whether to include a site in multi-service broadcast posts. Note that some data, including the character count, aren't available in older versions of StatusNet.

Here's a patch to Adium 1.4beta which provides an example of checking this data (Obj-C).


 * statusnet/version. 
 * Formats: xml, json
 * Sample: http://identi.ca/api/statusnet/version.xml

Version number, typically major.minor.patch, like "0.9.2".