AtomPub
StatusNet 0.9.7 will support the Atom Publication Protocol ("APP" or "AtomPub") as an API. This document details how the API works.
Contents |
Authentication
The API supports both HTTP Basic and OAuth.
Service document
The service document for an account is found at /api/statusnet/app/service/<nickname>.xml.
Each service document has one workspace ('Main') and four collections:
- notices
- notices generated by the user
- subscriptions
- subscriptions by the user
- favorites
- the user's favorites
- memberships
- the user's group memberships
Collections are identified by the <activity:verb> element(s) in their <collection> element.
Notices
The feed of notices, in reverse-chronological order, is at /api/statuses/user_timeline/<id>.atom.
This is a partial feed; navigation links are included in the feed to scroll forward and back.
Normal notices will be represented as Activity Streams events with verb = Post, object-type = Note.
Repeats will be represented as Activity Streams events with verb = Share, and with the activity object being an entry representing a "normal notice".
Posted files will be represented with verb = Post and object-type = Image, File, Video, etc.
Single-notice URL
A single notice will be available as an Activity Streams event at /api/statuses/show/<notice-id>.atom.
Posting a notice
The user posts a notice by sending a POST request containing a single <entry> element to the URL of the notice feed. These should have verb = Post, and object-type = Note, but since these are the default values, Atom entries that aren't marked up as Activity Streams objects should be fine to post.
The resulting entry will be returned, per the APP, in Activity Streams format. The location of the notice can be read from the Content-Location HTTP header of the result or from the rel=self URL in the resulting entry.
Editing a notice
Notices in StatusNet cannot be edited. PUT requests to a notice URL will fail.
Deleting a notice
A single notice can be deleted by posting a DELETE HTTP request to the notice's Atom representation.
Subscriptions
The feed of subscriptions, in reverse-chronological order, is at /api/statusnet/app/subscriptions/<id>.atom.
This is a partial feed; it includes the navigation links necessary to scroll forward and back.
Subscriptions are represented as Activity Streams entries with verb = Follow and object-type = Person.
Subscription URL
A subscription has an URL at /api/statusnet/app/subscriptions/<subscriber id>/<subscribed id>.atom.
Adding a new subscription
To add a new subscription, POST an Activity Streams <entry> with verb = Follow and object-type = Person.
The resulting entry will be returned, per the APP, in Activity Streams format. The location of the subscription can be read from the Content-Location HTTP header of the result or from the rel=self URL in the resulting entry.
Editing a subscription
Subscriptions cannot be edited. PUT requests to the subscription URL will result in an error.
Deleting a subscription
To delete a subscription, send a DELETE HTTP request to the Subscription URL.
Favorites
The feed of the user's favorites, in reverse-chronological order, is at /api/statusnet/app/favorites/<user id>.atom.
This is a partial feed; it includes the navigation links necessary to scroll forward and back.
Favorites are represented as Activity Streams entries with verb = Favorite and object-type = Note.
Favorite URL
Favorite entries have a self URL at /api/statusnet/app/favorites/<user id>/<notice id>.atom.
Favoriting a notice
To favorite a notice, POST an Activity Streams <entry> with verb = Favorite and object-type = Note.
The resulting favorite will be returned, per the APP, in Activity Streams format. The location of the favorite can be read from the Content-Location HTTP header of the result or from the rel=self URL in the resulting entry.
Editing a favorite
Favorites are immutable in StatusNet.
Deleting a favorite
To "unfavorite" a notice, POST a DELETE request to the URL for the favorite.
Groups
A feed of group memberships, in reverse-chron order, is available at /api/statusnet/app/memberships/<user id>.atom.
This is a partial feed; it includes the navigation links necessary to scroll forward and back.
Memberships are represented as activity entries with verb = Join and object-type = Group.
Membership URL
Each membership has a representation at /api/statusnet/app/memberships/<user id>/<group id>.atom.
Joining a group
To join a group, POST an activity entry with verb = Join and object-type = Group to the memberships feed.
The resulting membership will be returned, per the APP, in Activity Streams format. The location of the membership can be read from the Content-Location HTTP header of the result or from the rel=self URL in the resulting entry.
Editing group membership
Not possible.
Leaving a group
To leave a group, send a DELETE request to the membership URL.
Future
Compatibility
There's a CLI script to run test cases in tests/atompub. Pass it the username and password of a local account on your site and it'll attempt to connect up and confirm that some basic things work.
More generally, we need to wrassle up some actual AtomPub-based posting clients and see if they work!
Tested AtomPub clients:
| App | Date | Status | Notes |
|---|---|---|---|
| MarsEdit 3.1.4 | 2010-12-14 | OK | Discovery via RSD; asks for username and password. Shows your list of posts automatically, and posting is pretty natural except for title/content split not really matching well. |
| flickr blog posting | 2010-12-14 | FAIL | No discovery, but if you provide the URL to your profile's Atom feed it will connect. Cannot auth due to exclusive use of WSSE instead of basic auth or oAuth (see notes on AtomPub and WSSE -- looks like if it's using that style it requires cleartext passwords stored on server, so not doable for us). Since auth is busted, can't post. |
| .. | .. | .. | .. |
Untested:
-
Windows Live blog edity thingyWindows Live Writer
