doc-src/atompub

   1 > The Atom Publishing Protocol (AtomPub) is an application-level
   2 > protocol for publishing and editing Web resources.  The protocol is
   3 > based on HTTP transfer of Atom-formatted representations.  The Atom
   4 > format is documented in the Atom Syndication Format.
   5
   6 You can find more information about AtomPub in [RFC5023](https://tools.ietf.org/html/rfc5023).
   7
   8 > Activity Streams is an open format specification for activity stream protocols,
   9 > which are used to syndicate activities taken in social web applications and
  10 > services.
  11
  12 You can find more information about Activity Streams at [activitystrea.ms](http://activitystrea.ms/).
  13
  14 ## Authentication
  15
  16 The API supports both
  17 [HTTP Basic](https://en.wikipedia.org/wiki/Basic_access_authentication)
  18 and [OAuth](https://en.wikipedia.org/wiki/OAuth).
  19
  20 ## Service document
  21
  22 The service document for an account is found at
  23 `/api/statusnet/app/service/<nickname>.xml`
  24
  25 Each service document has one workspace ('Main') and four collections:
  26
  27 * **notices**: notices generated by the user
  28 * **subscriptions**: subscriptions by the user
  29 * **favorites**: the user's favorites
  30 * **memberships**: the user's group memberships
  31
  32 Collections are identified by the `<activity:verb>` element(s) in their
  33 `<collection>` element.
  34
  35 ## Notices
  36
  37 Notice feeds, in reverse-chronological order, are at
  38 `/api/statuses/user_timeline/<id>.atom`.
  39
  40 This is a partial feed; navigation links are included in the feed to scroll forward
  41 and back.
  42
  43 Notices are represented as Activity Streams events with the "Post" verb and "Note" object-type:
  44
  45     <entry>
  46      <activity:object-type>
  47        http://activitystrea.ms/schema/1.0/note
  48      </activity:object-type>
  49      [...]
  50      <activity:verb>
  51        http://activitystrea.ms/schema/1.0/post
  52      </activity:verb>
  53      [...]
  54     </entry>
  55
  56 Repeats are be represented as Activity Streams events with the "Share" verb, and with the activity object being an entry representing a Notice:
  57
  58     <entry>
  59      <activity:verb>
  60        http://activitystrea.ms/schema/1.0/share
  61      </activity:verb>
  62      [...]
  63      <activity:object>
  64       <activity:object-type>
  65         http://activitystrea.ms/schema/1.0/activity
  66       </activity:object-type>
  67       [...]
  68       <activity:verb>
  69         http://activitystrea.ms/schema/1.0/post
  70       </activity:verb>
  71       [...]
  72       <activity:object>
  73        <activity:object-type>
  74          http://activitystrea.ms/schema/1.0/note
  75        </activity:object-type>
  76        [...]
  77       </activity:object>
  78       [...]
  79      </activity:object>
  80      [...]
  81     </entry>
  82
  83 Posted files will be represented by the "Post" verb and "Image, File, Video" object-type.
  84
  85 ### Single-notice URL
  86
  87 Single notices are be available as an Activity Streams event at `/api/statuses/show/<notice-id>.atom`.
  88
  89     <entry>
  90      <activity:object-type>
  91       http://activitystrea.ms/schema/1.0/note
  92      </activity:object-type>
  93      [...]
  94      <activity:verb>
  95       http://activitystrea.ms/schema/1.0/post
  96      </activity:verb>
  97      <author>
  98       <activity:object-type>
  99        http://activitystrea.ms/schema/1.0/person
 100       </activity:object-type>
 101       [...]
 102      </author>
 103     </entry>
 104
 105 ### Posting a notice
 106
 107 A notice can be posted by sending a POST request containing a single `<entry>`
 108 element to the URL of the notice feed. These should have a "Post" verb, and a "Note"
 109 object-type, but since these are the default values, Atom entries that aren't
 110 marked up as Activity Streams objects should be fine to post.
 111
 112 The resulting entry will be returned, per the APP, in Activity Streams format. The
 113 location of the notice can be read from the Content-Location HTTP header of the
 114 result or from the rel=self URL in the resulting entry.
 115
 116 ### Editing a notice
 117
 118 Notices cannot be edited. PUT requests to a notice URL will fail.
 119
 120 ### Deleting a notice
 121
 122 A single notice can be deleted by posting a DELETE HTTP request to the notice's
 123 Atom representation.
 124
 125 Example with cURL:
 126
 127     curl -u username:password -X DELETE \
 128       http://example.org/api/statuses/show/<notice-id>.atom
 129
 130 ## Subscriptions
 131
 132 The subscriptions feed, in reverse-chronological order, is at
 133 `/api/statusnet/app/subscriptions/<id>.atom`.
 134
 135 This is a partial feed; it includes the navigation links necessary to scroll forward
 136 and back.
 137
 138 Subscriptions are represented as Activity Streams entries with the "Follow" verb and
 139 "Person" object-type.
 140
 141 ### Subscription URL
 142
 143 A subscription has an URL at
 144 `/api/statusnet/app/subscriptions/<subscriber id>/<subscribed id>.atom`.
 145
 146 ### Adding a new subscription
 147
 148 To add a new subscription, POST an Activity Streams `<entry>` with a "Follow" verb
 149 and "Person" object-type.
 150
 151 The resulting entry will be returned, per the APP, in Activity Streams format. The
 152 location of the subscription can be read from the Content-Location HTTP header of
 153 the result or from the rel=self URL in the resulting entry.
 154
 155 ### Editing a subscription
 156
 157 Subscriptions cannot be edited. PUT requests to the subscription URL will result in
 158 an error.
 159
 160 ### Deleting a subscription
 161
 162 To delete a subscription, send a DELETE HTTP request to the Subscription URL.
 163
 164 ## Favorites
 165
 166 The feed of the user's favorites, in reverse-chronological order, is at
 167 `/api/statusnet/app/favorites/<user id>.atom`.
 168
 169 This is a partial feed; it includes the navigation links necessary to scroll forward
 170 and back.
 171
 172 Favorites are represented as Activity Streams entries with the "Favorite" verb and
 173 "Note" object-type.
 174
 175 ### Favorite URL
 176
 177 Favorite entries have a self URL at
 178 `/api/statusnet/app/favorites/<user id>/<notice id>.atom`.
 179
 180 ### Favoriting a notice
 181
 182 To favorite a notice, POST an Activity Streams `<entry>` with the "Favorite" verb and
 183 "Note" object-type.
 184
 185 The resulting favorite will be returned, per the APP, in Activity Streams format.
 186 The location of the favorite can be read from the Content-Location HTTP header of
 187 the result or from the rel=self URL in the resulting entry.
 188
 189 ### Editing a favorite
 190
 191 Favorites cannot be edited. PUT requests to a favorite URL will fail.
 192
 193 ### Deleting a favorite
 194
 195 To "unfavorite" a notice, POST a DELETE request to the URL for the favorite.
 196
 197 ## Groups
 198
 199 A feed of group memberships, in reverse-chron order, is available at
 200 `/api/statusnet/app/memberships/<user id>.atom`.
 201
 202 This is a partial feed; it includes the navigation links necessary to scroll forward
 203 and back.
 204
 205 Memberships are represented as Activity Streams entries with the "Join" ber and
 206 "Group" object-type.
 207
 208 ### Membership URL
 209
 210 Each membership has a representation at
 211 `/api/statusnet/app/memberships/<user id>/<group id>.atom`.
 212
 213 ### Joining a group
 214
 215 To join a group, POST an activity entry with a "Join" verb and "Group" object-type to
 216 the memberships feed.
 217
 218 The resulting membership will be returned, per the APP, in Activity Streams format.
 219 The location of the membership can be read from the Content-Location HTTP header of
 220 the result or from the rel=self URL in the resulting entry.
 221
 222 ### Editing group membership
 223
 224 Group memberships cannot be edited. PUT requests to a membership feed will fail.
 225
 226 ### Leaving a group
 227
 228 To leave a group, send a DELETE request to the membership URL.
 229