gnu-social/doc-src/atompub

> 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.