GNUsocial/gnu-social
4
0
Fork 1
Code Issues Releases Wiki Activity

Add AtomPub, Twitter-compat. API documentation to doc-src/

Browse Source
This commit is contained in:
Chimo 2015-11-24 12:59:43 -05:00
parent 5b847eff12
commit c95f74018d
4 changed files with 669 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
actions/rsd.php
View File

@ -151,7 +151,7 @@ class RsdAction extends Action
$this->elementStart('api', $apiAttrs);
$this->elementStart('settings');
$this->element('docs', null,
'http://status.net/wiki/TwitterCompatibleAPI');
common_local_url('doc', array('title' => 'api')));
$this->element('setting', array('name' => 'OAuth'),
'true');
$this->elementEnd('settings');

11
doc-src/api
View File

@ -2,5 +2,12 @@
<!-- Document licensed under Creative Commons Attribution 3.0 Unported. See -->
<!-- https://creativecommons.org/licenses/by/3.0/ for details. -->
%%site.name%% provides an API that applications can use to interact with it.
More information about this API can be found on the [StatusNet Wiki](http://status.net/wiki/API).
%%site.name%% provides APIs that applications can use to interact with it:
* [AtomPub](atompub)
* [Twitter-compatible API](twitterapi)
## API discovery
The base URLs for the APIs can be obtained using [Really Simple Discovery](https://en.wikipedia.org/wiki/Really_Simple_Discovery).

229
doc-src/atompub Normal file
View 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.

430
doc-src/twitterapi Normal file
View File

@ -0,0 +1,430 @@
## Authentication
### HTTP Basic authentication
The API uses [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
Note that this means that users with only an OpenID login cannot use the API; they have to add a
password to their account using the control panel on the site.
### OAuth authentication
OAuth 1.0a authentication for API resources is also supported. Generally, StatusNet's
UI and API are similar to Twitter's for OAuth applications (if you're new to OAuth
check out [Beginner’s Guide to OAuth](http://hueniverse.com/oauth/)).
To use OAuth, you'll need to register your client application via the web interface
and obtain a consumer key and secret. You can find the interface for application
registration at [http://%%site.server%%/%%site.path%%settings/oauthapps](http://%%site.server%%/%%site.path%%settings/oauthapps).
## JSONP callbacks
For API methods that return [JSON](https://en.wikipedia.org/wiki/JSON), an optional
JSONP-style callback parameter is supported. If supplied, the response will be in
JSONP format with a callback of the given name. To make it easier for clients to
handle error conditions, HTTP error codes are suppressed, and the errors will be
returned in the response body when using JSONP.
## Rate limiting
There is currently no rate-limiting.
## Gotchas
Some things to remember:
* %%site.name%% supports the
[OStatus federation protocol](https://en.wikipedia.org/wiki/OStatus) (as well as
[OpenMicroBlogging](https://en.wikipedia.org/wiki/OpenMicroBlogging) for backwards
compatibility), so many notices and friends' profiles may come from other servers.
* User nicknames are unique, but they are not globally unique. Use the ID number
instead.
* Private streams are not implemented yet.
* GNU social sites can be configured as private. In that case, all API methods
require authentication, including the public timeline (see the 'config' method
below).
* If "Fancy URLs" are not enabled, urls from above need to include "index.php" at
the root. ( e.g. http://example.org/statusnet/api becomes http://www.example.org/statusnet/index.php/api )
* The `since_id` parameter does not work as documented by Twitter. Twitter says of
`since_id`: "There are limits to the number of Tweets which can be accessed
through the API. If the limit of Tweets has occured since the `since_id`, the
`since_id` will be forced to the oldest ID available." However, GNU social will
return the newest notices (or the newest back from max_id, if present)! Also, a
`since_id` <= 0 will be ignored.
## Timeline resources
### statuses/public_timeline
Returns the 20 most recent notices, including repeats if they exist, from
non-protected users.
### statuses/home_timeline
Returns the 20 most recent notices, including repeats if they exist, posted by the
authenticating user and the users they follow. This is the same timeline seen by a
user when they login to their instance. This method is identical to
statuses/friends_timeline, except that this method always includes repeats.
### statuses/friends_timeline
Alias of statuses/home_timeline
### statuses/friends_timeline/:username
Alias of statuses/home_timeline for the specified username
### statuses/mentions
Returns the 20 most recent mentions (notices containing @username) for the
authenticating user.
This method will not include repeats in the XML and JSON responses unless the
include_rts parameter is set. The RSS and Atom responses will always include repeats
as notices prefixed with RT.
### statuses/replies
Alias of statuses/mentions
### statuses/replies/:username
Alias of statuses/mentions for the specified username
### statuses/user_timeline
Returns the 20 most recent notices posted by the authenticating user. It is also
possible to request another user's timeline by using the screen\_name or user_id
parameter. The other users timeline will only be visible if they are not protected,
or if the authenticating user's follow request was accepted by the protected user.
This method will not include repeats in the XML and JSON responses unless the
include_rts parameter is set. The RSS and Atom responses will always include
repeats as notices prefixed with RT, regardless of provided parameters.
### statuses/retweeted\_to_me
Not implemented.
### statuses/retweeted\_by_me
Not implemented.
### statuses/retweets\_of_me
Not implemented.
## Status resources
### statuses/show/:id
Returns a single notice, specified by the id parameter. The notice's author will be
returned inline.
### statuses/update
Post a new notice as the authenticating user.
Additional 'media' parameter allows binary multimedia uploads (images, etc.). Format
post data as multipart/form-data when using the 'media' parameter.
### statuses/destroy/:id
Destroys the notice specified by the required ID parameter. The authenticating user
must be the author of the specified notice. Returns the destroyed notice if successful.
### statuses/retweet/:id
Repeats a notice. Returns the original notice with repeat details embedded.
## User resources
### statuses/friends
Returns the user's subscriptions (friends) as an array of profiles.
### statuses/followers
Returns the user's subscribers (followers) as an array of profiles.
### users/show
Returns extended information of a given user, specified by ID or screen name as per
the required id parameter.
## Direct message resources
### direct_messages
Returns the 20 most recent direct messages sent to the authenticating user. The XML
and JSON versions include detailed information about the sender and recipient user.
### direct_messages/sent
Returns the 20 most recent direct messages sent by the authenticating user. The XML
and JSON versions include detailed information about the sender and recipient user.
### direct_messages/new
Sends a new direct message to the specified user from the authenticating user.
Requires both the user and text parameters and must be a POST. Returns the sent
message in the requested format if successful.
### direct_messages/destroy
Not implemented.
## Friendships resources
### friendships/create
Allows the authenticating users to follow the user specified in the ID parameter.
Returns the befriended user in the requested format when successful. Returns a
string describing the failure condition when unsuccessful.
If you are already friends with the user a HTTP 403 may be returned, though for
performance reasons you may get a 200 OK message even if the friendship already
exists.
Note that users cannot subscribe to remote profiles using this API.
### friendships/destroy
Allows the authenticating users to unfollow the user specified in the ID parameter.
Returns the unfollowed user in the requested format when successful. Returns a
string describing the failure condition when unsuccessful.
Users can unsubscribe to a remote profile using this API, but it's preferred to use
numeric IDs to nicknames.
### friendships/exists
Test for the existence of friendship between two users. Will return true if user\_a
follows user_b, otherwise will return false. Authentication is required if either
user A or user B are protected. Additionally the authenticating user must be a
follower of the protected user.
### friendships/show
Returns detailed information about the relationship between two users.
## Friends and subscribers resources
### friends/ids
Returns an array of numeric IDs for every user the specified user is subscribed to.
This method is powerful when used in conjunction with users/lookup.
### followers/ids
Returns an array of numeric IDs for every user subscsribed to the specified user.
This method is powerful when used in conjunction with users/lookup.
## Account resources
### account/verify_credentials
Returns an HTTP 200 OK response code and a representation of the requesting user if
authentication was successful; returns a 401 status code and an error message if
not. Use this method to test if supplied user credentials are valid.
### account/end_session
Not implemented.
### account/update\_delivery_device
Not implemented.
### account/rate\_limit_status
Returns the remaining number of API requests available to the requesting user before
the API limit is reached.
We have no rate limit, so this always returns 150 hits left.
### account/update\_profile\_background_image
Updates the authenticating user's profile background image. This method can also be
used to enable or disable the profile background image.
### account/update\_profile_image
Updates the authenticating user's profile image. Note that this method expects raw
multipart data, not a URL to an image.
## Favorite resources
### favorites
Returns the 20 most recent favorite statuses for the authenticating or specified
user in the requested format.
### favorites/create/:id
Favorites the status specified in the ID parameter as the authenticating user.
Returns the favorite status when successful.
### favorites/destroy/:id
Un-favorites the status specified in the ID parameter as the authenticating user.
Returns the un-favorited status in the requested format when successful.
## Notification resources
### notifications/follow
Not implemented.
### notifications/leave
Not implemented.
## Block resources
### blocks/create
Blocks the specified user from following the authenticating user. In addition the
blocked user will not show in the authenticating users mentions or timeline (unless
retweeted by another user). If a follow or friend relationship exists it is
destroyed.
### blocks/destroy
Un-blocks the user specified in the ID parameter for the authenticating user.
Returns the un-blocked user in the requested format when successful. If
relationships existed before the block was instated, they will not be restored.
### blocks/exists
Not implemented.
### blocks/blocking
Not implemented.
## Help resources
### help/test
Returns the string "ok" in the requested format with a 200 OK HTTP status code. This
method is great for sending a HEAD request to determine our servers current time.
## OAuth resources
It is strongly recommended you use HTTPS for all OAuth authorization steps.
### oauth/request_token
Allows a Consumer application to obtain an OAuth Request Token to request user
authorization. This method fulfills Section 6.1 of the OAuth 1.0 authentication
flow. It is strongly recommended you use HTTPS for all OAuth authorization steps.
### oauth/authorize
Allows a Consumer application to use an OAuth Request Token to request user
authorization. This method fulfills Section 6.2 of the OAuth 1.0 authentication
flow. Desktop applications must use this method (and cannot use GET oauth/authenticate).
### oauth/access_token
Allows a Consumer application to exchange the OAuth Request Token for an OAuth
Access Token. This method fulfills Section 6.3 of the OAuth 1.0 authentication flow.
The OAuth access token may also be used for xAuth operations.
## Search
The search method supports the following optional URL parameters:
* **callback**: if supplied when using the JSON format, the response will use the
JSONP format with a callback of the given name.
* **rpp**: the number of notices to return per page, up to a max of 100.
* **page**: the page number (starting at 1) to return.
* **since_id:**: returns notices with ids greater than the given id.
Note:
* The search does not support operators, such as "from:", "to:" and booleans.
* Notice content is HTML-encoded.
### search
Returns relevant notices that match a specified query.
### Atom
To request search results in Atom, append your URL-encoded query as a parameter to
the search method and specify the Atom format:
`%%site.server%%/%%site.path%%api/search.atom?q=<query>`
### JSON
To request search results in JSON, append your URL-encoded query as a parameter to
the search method and specify the JSON format:
`%%site.server%%/%%site.path%%api/search.json?q=<query>`
## Additional resources
These are extensions to the Twitter API that expose additional functionality.
### Group resources
#### statusnet/groups/timeline
Shows a group's timeline. Similar to other timeline resources.
#### statusnet/groups/show
Show a groups profile.
#### statusnet/groups/create
Create a new group.
#### statusnet/groups/join
Join a group.
#### statusnet/groups/leave
Leave a group.
#### statusnet/groups/list
Show the groups a given user is a member of.
#### statusnet/groups/list_all
List all local groups.
#### statusnet/groups/membership
List the members of a given group.
#### statusnet/groups/is_member
Determine whether a given user is a member of a given group.
### Tag resources
#### statusnet/tags/timeline
Shows a tag's timeline. Similar to other timeline resources.
### Media resources
#### statusnet/media/upload
Endpoint for uploading an image. Returns a URL that can be used in a status update.
Format post data as multipart/form-data.
### Configuration
#### statusnet/config
Show an instance's configuration information.
Of special note is the `<private>` element (config/site/private), which indicates
whether a site is private. When a site is configured as private every other API
method requires authentication, including the public timeline (`/api/statuses/public_timeline.format`).