API discovery

From StatusNet
Jump to: navigation, search

Contents

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:

  • #Finding the API root
    • 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:

  • #Getting server info
    • 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 <link rel="EditURI" type="application/rsd+xml"> in the site's home page:

 <link rel="EditURI" type="application/rsd+xml" href="http://identi.ca/rsd.xml"/>

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

 <?xml version="1.0" encoding="UTF-8"?>
 <rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
   <service>
     <engineName>StatusNet</engineName>
     <engineLink>http://status.net/</engineLink>
     <apis>
       <api name="Twitter" preferred="true" apiLink="https://identi.ca/api/" blogID="">
         <settings>
           <docs>http://status.net/wiki/TwitterCompatibleAPI</docs>
           <setting name="OAuth">true</setting>
         </settings>
       </api>
     </apis>
   </service>
 </rsd>

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

Getting server info

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).

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

Personal tools
Namespaces
Variants
Actions
Navigation
Status.net
Toolbox