atompub 6.9 KB

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