Add AtomPub, Twitter-compat. API documentation to doc-src/
This commit is contained in:
Chimo
229
doc-src/atompub
Normal file
229
doc-src/atompub
Normal file
@@ -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/<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.
|
||||
|
||||
Reference in New Issue
Block a user