X-Git-Url: https://git.mxchange.org/?p=quix0rs-gnu-social.git;a=blobdiff_plain;f=doc-src%2Fatompub;fp=doc-src%2Fatompub;h=6870bd2ad09400754374e15d29a6410035f38338;hp=0000000000000000000000000000000000000000;hb=4160a3fb730113f3d712bd777884c4b0482f6df1;hpb=abd90bbdf562614755802885dfb5673645df8575 diff --git a/doc-src/atompub b/doc-src/atompub new file mode 100644 index 0000000000..6870bd2ad0 --- /dev/null +++ b/doc-src/atompub @@ -0,0 +1,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/.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 `` element(s) in their +`` element. + +## Notices + +Notice feeds, in reverse-chronological order, are at +`/api/statuses/user_timeline/.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: + + + + http://activitystrea.ms/schema/1.0/note + + [...] + + http://activitystrea.ms/schema/1.0/post + + [...] + + +Repeats are be represented as Activity Streams events with the "Share" verb, and with the activity object being an entry representing a Notice: + + + + http://activitystrea.ms/schema/1.0/share + + [...] + + + http://activitystrea.ms/schema/1.0/activity + + [...] + + http://activitystrea.ms/schema/1.0/post + + [...] + + + http://activitystrea.ms/schema/1.0/note + + [...] + + [...] + + [...] + + +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/.atom`. + + + + http://activitystrea.ms/schema/1.0/note + + [...] + + http://activitystrea.ms/schema/1.0/post + + + + http://activitystrea.ms/schema/1.0/person + + [...] + + + +### Posting a notice + +A notice can be posted by sending a POST request containing a single `` +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/.atom + +## Subscriptions + +The subscriptions feed, in reverse-chronological order, is at +`/api/statusnet/app/subscriptions/.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//.atom`. + +### Adding a new subscription + +To add a new subscription, POST an Activity Streams `` 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/.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//.atom`. + +### Favoriting a notice + +To favorite a notice, POST an Activity Streams `` 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/.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//.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. +