forked from GNUsocial/gnu-social
230 lines
6.9 KiB
Plaintext
230 lines
6.9 KiB
Plaintext
> 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.
|
|
|