git.gnu.io has moved to IP address 209.51.188.249 -- please double check where you are logging in.

atompub 6.92 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
> The Atom Publishing Protocol (AtomPub) is an application-level
> protocol for publishing and editing Web resources.  The protocol is
> based on HTTP transfer of Atom-formatted representations.  The Atom
> format is documented in the Atom Syndication Format.

You can find more information about AtomPub in [RFC5023](https://tools.ietf.org/html/rfc5023).

> Activity Streams is an open format specification for activity stream protocols,
> which are used to syndicate activities taken in social web applications and
> services.

You can find more information about Activity Streams at [activitystrea.ms](http://activitystrea.ms/).

## Authentication

The API supports both
[HTTP Basic](https://en.wikipedia.org/wiki/Basic_access_authentication)
and [OAuth](https://en.wikipedia.org/wiki/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

Notice feeds, in reverse-chronological order, are at
`/api/statuses/user_timeline/<id>.atom`.

This is a partial feed; navigation links are included in the feed to scroll forward
and back.

Notices are represented as Activity Streams events with the "Post" verb and "Note" object-type:

    <entry>
     <activity:object-type>
       http://activitystrea.ms/schema/1.0/note
     </activity:object-type>
     [...]
     <activity:verb>
       http://activitystrea.ms/schema/1.0/post
     </activity:verb>
     [...]
    </entry>

Repeats are be represented as Activity Streams events with the "Share" verb, and with the activity object being an entry representing a Notice:

    <entry>
     <activity:verb>
       http://activitystrea.ms/schema/1.0/share
     </activity:verb>
     [...]
     <activity:object>
      <activity:object-type>
        http://activitystrea.ms/schema/1.0/activity
      </activity:object-type>
      [...]
      <activity:verb>
        http://activitystrea.ms/schema/1.0/post
      </activity:verb>
      [...]
      <activity:object>
       <activity:object-type>
         http://activitystrea.ms/schema/1.0/note
       </activity:object-type>
       [...]
      </activity:object>
      [...]
     </activity:object>
     [...]
    </entry>

Posted files will be represented by the "Post" verb and "Image, File, Video" object-type.

### Single-notice URL

Single notices are be available as an Activity Streams event at `/api/statuses/show/<notice-id>.atom`.

    <entry>
     <activity:object-type>
      http://activitystrea.ms/schema/1.0/note
     </activity:object-type>
     [...]
     <activity:verb>
      http://activitystrea.ms/schema/1.0/post
     </activity:verb>
     <author>
      <activity:object-type>
       http://activitystrea.ms/schema/1.0/person
      </activity:object-type>
      [...]
     </author>
    </entry>

### Posting a notice

A notice can be posted by sending a POST request containing a single `<entry>`
element to the URL of the notice feed. These should have a "Post" verb, and a "Note"
object-type, 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 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.

Example with cURL:

    curl -u username:password -X DELETE \
      http://example.org/api/statuses/show/<notice-id>.atom

## Subscriptions

The subscriptions feed, 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 the "Follow" verb and
"Person" object-type.

### 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 a "Follow" verb
and "Person" object-type.

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 the "Favorite" verb and
"Note" object-type.

### 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 the "Favorite" verb and
"Note" object-type.

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 cannot be edited. PUT requests to a favorite URL will fail.

### 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 Streams entries with the "Join" ber and
"Group" object-type.

### 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 a "Join" verb and "Group" object-type 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

Group memberships cannot be edited. PUT requests to a membership feed will fail.

### Leaving a group

To leave a group, send a DELETE request to the membership URL.