clones/friendica
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update API docs 

Add `friendica/notification` and `friendica/notification/seen` endpoints

Fix some list rendering issues

Move all `friendica/*` endpoints under "Implemented API calls (not compatible with other APIs)" section

Add info about permitted HTTP methods and required auth
This commit is contained in:
Fabrixxm 2016-02-08 10:22:12 +01:00
parent 756b90a4e0
commit 870d2f844d
1 changed files with 263 additions and 187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

450
doc/api.md
View File

@ -7,6 +7,21 @@ Please refer to the linked documentation for further information.
## Implemented API calls ## Implemented API calls
### General ### General
#### HTTP Method
API endpoints can restrict the method used to request them.
Using an invalid method results in HTTP error 405 "Method Not Allowed".
In this document, the required method is listed after the endpoint name. "*" means every method can be used.
#### Auth
Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.
OAuth settings can be added by the user in web UI under /settings/oauth/
In this document, endpoints which requires auth are marked with "AUTH" after endpoint name
#### Unsupported parameters #### Unsupported parameters
* cursor: Not implemented in GNU Social * cursor: Not implemented in GNU Social
* trim_user: Not implemented in GNU Social * trim_user: Not implemented in GNU Social
@ -37,36 +52,37 @@ Error body is
json: json:
``` ```
{ {
"error": "Specific error message", "error": "Specific error message",
"request": "API path requested", "request": "API path requested",
"code": "HTTP error code" "code": "HTTP error code"
} }
``` ```
xml: xml:
``` ```
<status> <status>
<error>Specific error message</error> <error>Specific error message</error>
<request>API path requested</request> <request>API path requested</request>
<code>HTTP error code</code> <code>HTTP error code</code>
</status> </status>
``` ```
--- ---
### account/rate_limit_status ### account/rate_limit_status (*; AUTH)
--- ---
### account/verify_credentials ### account/verify_credentials (*; AUTH)
#### Parameters #### Parameters
* skip_status: Don't show the "status" field. (Default: false) * skip_status: Don't show the "status" field. (Default: false)
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
--- ---
### conversation/show ### conversation/show (*; AUTH)
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id. Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
#### Parameters #### Parameter
* id: id of the post * id: id of the post
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -80,7 +96,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
* contributor_details * contributor_details
--- ---
### direct_messages ### direct_messages (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -93,7 +109,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
* skip_status * skip_status
--- ---
### direct_messages/all ### direct_messages/all (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -102,7 +118,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
* getText: Defines the format of the status field. Can be "html" or "plain" * getText: Defines the format of the status field. Can be "html" or "plain"
--- ---
### direct_messages/conversation ### direct_messages/conversation (*; AUTH)
Shows all direct messages of a conversation Shows all direct messages of a conversation
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
@ -113,7 +129,7 @@ Shows all direct messages of a conversation
* uri: URI of the conversation * uri: URI of the conversation
--- ---
### direct_messages/new ### direct_messages/new (POST,PUT; AUTH)
#### Parameters #### Parameters
* user_id: id of the user * user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!) * screen_name: screen name (for technical reasons, this value is not unique!)
@ -122,7 +138,7 @@ Shows all direct messages of a conversation
* title: Title of the direct message * title: Title of the direct message
--- ---
### direct_messages/sent ### direct_messages/sent (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -132,7 +148,7 @@ Shows all direct messages of a conversation
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
--- ---
### favorites ### favorites (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -144,22 +160,23 @@ Shows all direct messages of a conversation
* user_id * user_id
* screen_name * screen_name
Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array. Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.
Set this values will result in an empty array.
--- ---
### favorites/create ### favorites/create (POST,PUT; AUTH)
#### Parameters #### Parameters
* id * id
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
--- ---
### favorites/destroy ### favorites/destroy (POST,DELETE; AUTH)
#### Parameters #### Parameters
* id * id
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
--- ---
### followers/ids ### followers/ids (*; AUTH)
#### Parameters #### Parameters
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
@ -171,139 +188,7 @@ Favorites aren't displayed to other users, so "user_id" and "screen_name". So se
Friendica doesn't allow showing followers of other users. Friendica doesn't allow showing followers of other users.
--- ---
### friendica/activity/<verb> ### friends/ids (*; AUTH)
#### parameters
* id: item id
Add or remove an activity from an item.
'verb' can be one of:
- like
- dislike
- attendyes
- attendno
- attendmaybe
To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
Attend verbs should be used only with event-related items (there is no check at the moment)
#### Return values
On success:
json
```"ok"```
xml
```<ok>true</ok>```
On error:
HTTP 400 BadRequest
---
### friendica/photo
#### Parameters
* photo_id: Resource id of a photo.
* scale: (optional) scale value of the photo
Returns data of a picture with the given resource.
If 'scale' isn't provided, returned data include full url to each scale of the photo.
If 'scale' is set, returned data include image data base64 encoded.
possibile scale value are:
0: original or max size by server settings
1: image with or height at <= 640
2: image with or height at <= 320
3: thumbnail 160x160
4: Profile image at 175x175
5: Profile image at 80x80
6: Profile image at 48x48
An image used as profile image has only scale 4-6, other images only 0-3
#### Return values
json
```
{
"id": "photo id"
"created": "date(YYYY-MM-GG HH:MM:SS)",
"edited": "date(YYYY-MM-GG HH:MM:SS)",
"title": "photo title",
"desc": "photo description",
"album": "album name",
"filename": "original file name",
"type": "mime type",
"height": "number",
"width": "number",
"profile": "1 if is profile photo",
"link": {
"<scale>": "url to image"
...
},
// if 'scale' is set
"datasize": "size in byte",
"data": "base64 encoded image data"
}
```
xml
```
<photo>
<id>photo id</id>
<created>date(YYYY-MM-GG HH:MM:SS)</created>
<edited>date(YYYY-MM-GG HH:MM:SS)</edited>
<title>photo title</title>
<desc>photo description</desc>
<album>album name</album>
<filename>original file name</filename>
<type>mime type</type>
<height>number</height>
<width>number</width>
<profile>1 if is profile photo</profile>
<links type="array">
<link type="mime type" scale="scale number" href="image url"/>
...
</links>
</photo>
```
---
### friendica/photos/list
Returns a list of all photo resources of the logged in user.
#### Return values
json
```
[
{
id: "resource_id",
album: "album name",
filename: "original file name",
type: "image mime type",
thumb: "url to thumb sized image"
},
...
]
```
xml
```
<photos type="array">
<photo id="resource_id"
album="album name"
filename="original file name"
type="image mime type">
"url to thumb sized image"
</photo>
...
</photos>
```
---
### friends/ids
#### Parameters #### Parameters
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false) * stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
@ -315,15 +200,15 @@ xml
Friendica doesn't allow showing friends of other users. Friendica doesn't allow showing friends of other users.
--- ---
### help/test ### help/test (*)
--- ---
### media/upload ### media/upload (POST,PUT; AUTH)
#### Parameters #### Parameters
* media: image data * media: image data
--- ---
### oauth/request_token ### oauth/request_token (*)
#### Parameters #### Parameters
* oauth_callback * oauth_callback
@ -331,7 +216,7 @@ Friendica doesn't allow showing friends of other users.
* x_auth_access_type * x_auth_access_type
--- ---
### oauth/access_token ### oauth/access_token (*)
#### Parameters #### Parameters
* oauth_verifier * oauth_verifier
@ -341,7 +226,7 @@ Friendica doesn't allow showing friends of other users.
* x_auth_mode * x_auth_mode
--- ---
### statuses/destroy ### statuses/destroy (POST,DELETE; AUTH)
#### Parameters #### Parameters
* id: message number * id: message number
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
@ -350,15 +235,21 @@ Friendica doesn't allow showing friends of other users.
* trim_user * trim_user
--- ---
### statuses/followers ### statuses/followers (*; AUTH)
#### Parameters
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
--- ---
### statuses/friends ### statuses/friends (*; AUTH)
#### Parameters
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
--- ---
### statuses/friends_timeline ### statuses/friends_timeline (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -374,7 +265,7 @@ Friendica doesn't allow showing friends of other users.
* contributor_details * contributor_details
--- ---
### statuses/home_timeline ### statuses/home_timeline (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -390,7 +281,7 @@ Friendica doesn't allow showing friends of other users.
* contributor_details * contributor_details
--- ---
### statuses/mentions ### statuses/mentions (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -404,7 +295,7 @@ Friendica doesn't allow showing friends of other users.
* contributor_details * contributor_details
--- ---
### statuses/public_timeline ### statuses/public_timeline (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -418,7 +309,7 @@ Friendica doesn't allow showing friends of other users.
* trim_user * trim_user
--- ---
### statuses/replies ### statuses/replies (*; AUTH)
#### Parameters #### Parameters
* count: Items per page (default: 20) * count: Items per page (default: 20)
* page: page number * page: page number
@ -432,7 +323,7 @@ Friendica doesn't allow showing friends of other users.
* contributor_details * contributor_details
--- ---
### statuses/retweet ### statuses/retweet (POST,PUT; AUTH)
#### Parameters #### Parameters
* id: message number * id: message number
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
@ -441,7 +332,7 @@ Friendica doesn't allow showing friends of other users.
* trim_user * trim_user
--- ---
### statuses/show ### statuses/show (*; AUTH)
#### Parameters #### Parameters
* id: message number * id: message number
* conversation: if set to "1" show all messages of the conversation with the given id * conversation: if set to "1" show all messages of the conversation with the given id
@ -476,7 +367,7 @@ Friendica doesn't allow showing friends of other users.
* display_coordinates * display_coordinates
--- ---
### statuses/user_timeline ### statuses/user_timeline (*; AUTH)
#### Parameters #### Parameters
* user_id: id of the user * user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!) * screen_name: screen name (for technical reasons, this value is not unique!)
@ -489,15 +380,16 @@ Friendica doesn't allow showing friends of other users.
* include_entities: "true" shows entities for pictures and links (Default: false) * include_entities: "true" shows entities for pictures and links (Default: false)
#### Unsupported parameters #### Unsupported parameters
* include_rts * include_rts
* trim_user * trim_user
* contributor_details * contributor_details
--- ---
### statusnet/config ### statusnet/config (*)
--- ---
### statusnet/version ### statusnet/version (*)
#### Unsupported parameters #### Unsupported parameters
* user_id * user_id
@ -507,7 +399,7 @@ Friendica doesn't allow showing friends of other users.
Friendica doesn't allow showing followers of other users. Friendica doesn't allow showing followers of other users.
--- ---
### users/search ### users/search (*)
#### Parameters #### Parameters
* q: name of the user * q: name of the user
@ -517,7 +409,7 @@ Friendica doesn't allow showing followers of other users.
* include_entities * include_entities
--- ---
### users/show ### users/show (*)
#### Parameters #### Parameters
* user_id: id of the user * user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!) * screen_name: screen name (for technical reasons, this value is not unique!)
@ -533,8 +425,39 @@ Friendica doesn't allow showing friends of other users.
## Implemented API calls (not compatible with other APIs) ## Implemented API calls (not compatible with other APIs)
--- ---
### friendica/group_show ### friendica/activity/<verb>
#### parameters
* id: item id
Add or remove an activity from an item.
'verb' can be one of:
- like
- dislike
- attendyes
- attendno
- attendmaybe
To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"
Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".
Attend verbs should be used only with event-related items (there is no check at the moment)
#### Return values
On success:
json
```"ok"```
xml
```<ok>true</ok>```
On error:
HTTP 400 BadRequest
---
### friendica/group_show (*; AUTH)
Return all or a specified group of the user with the containing contacts as array. Return all or a specified group of the user with the containing contacts as array.
#### Parameters #### Parameters
@ -542,22 +465,23 @@ Return all or a specified group of the user with the containing contacts as arra
#### Return values #### Return values
Array of: Array of:
* name: name of the group * name: name of the group
* gid: id of the group * gid: id of the group
* user: array of group members (return from api_get_user() function for each member) * user: array of group members (return from api_get_user() function for each member)
--- ---
### friendica/group_delete ### friendica/group_delete (POST,DELETE; AUTH)
delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted. delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.
--- #### Parameters
### Parameters
* gid: id of the group to be deleted * gid: id of the group to be deleted
* name: name of the group to be deleted * name: name of the group to be deleted
#### Return values #### Return values
Array of: Array of:
* success: true if successfully deleted * success: true if successfully deleted
* gid: gid of the deleted group * gid: gid of the deleted group
* name: name of the deleted group * name: name of the deleted group
@ -566,19 +490,22 @@ Array of:
--- ---
### friendica/group_create ### friendica/group_create (POST,PUT; AUTH)
Create the group with the posted array of contacts as members. Create the group with the posted array of contacts as members.
#### Parameters #### Parameters
* name: name of the group to be created * name: name of the group to be created
#### POST data #### POST data
JSON data as Array like the result of „users/group_show“: JSON data as Array like the result of "users/group_show":
* gid * gid
* name * name
* array of users * array of users
#### Return values #### Return values
Array of: Array of:
* success: true if successfully created or reactivated * success: true if successfully created or reactivated
* gid: gid of the created group * gid: gid of the created group
* name: name of the created group * name: name of the created group
@ -587,26 +514,175 @@ Array of:
--- ---
### friendica/group_update ### friendica/group_update (POST)
Update the group with the posted array of contacts as members (post all members of the group to the call; function will remove members not posted). Update the group with the posted array of contacts as members (post all members of the group to the call; function will remove members not posted).
#### Parameters #### Parameters
* gid: id of the group to be changed * gid: id of the group to be changed
* name: name of the group to be changed * name: name of the group to be changed
#### POST data #### POST data
JSON data as array like the result of „users/group_show“: JSON data as array like the result of „users/group_show“:
* gid * gid
* name * name
* array of users * array of users
#### Return values #### Return values
Array of: Array of:
* success: true if successfully updated * success: true if successfully updated
* gid: gid of the changed group * gid: gid of the changed group
* name: name of the changed group * name: name of the changed group
* status: „missing user“ | „ok“ * status: „missing user“ | „ok“
* wrong users: array of users, which were not available in the contact table * wrong users: array of users, which were not available in the contact table
---
### friendica/notifications (GET)
Return last 50 notification for current user, ordered by date with unseen item on top
#### Parameters
none
#### Return values
Array of:
* id: id of the note
* type: type of notification as int (see NOTIFY_* constants in boot.php)
* name: full name of the contact subject of the note
* url: contact's profile url
* photo: contact's profile photo
* date: datetime string of the note
* timestamp: timestamp of the node
* date_rel: relative date of the note (eg. "1 hour ago")
* msg: note message in bbcode
* msg_html: note message in html
* msg_plain: note message in plain text
* link: link to note
* seen: seen state: 0 or 1
---
### friendica/notifications/seen (POST)
Set note as seen, returns item object if possible
#### Parameters
id: id of the note to set seen
#### Return values
If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.
If the note is not linked to an item, a success status is returned:
* "success" (json) | "&lt;status&gt;success&lt;/status&gt;" (xml)
---
### friendica/photo (*; AUTH)
#### Parameters
* photo_id: Resource id of a photo.
* scale: (optional) scale value of the photo
Returns data of a picture with the given resource.
If 'scale' isn't provided, returned data include full url to each scale of the photo.
If 'scale' is set, returned data include image data base64 encoded.
possibile scale value are:
* 0: original or max size by server settings
* 1: image with or height at <= 640
* 2: image with or height at <= 320
* 3: thumbnail 160x160
* 4: Profile image at 175x175
* 5: Profile image at 80x80
* 6: Profile image at 48x48
An image used as profile image has only scale 4-6, other images only 0-3
#### Return values
json
```
{
"id": "photo id"
"created": "date(YYYY-MM-GG HH:MM:SS)",
"edited": "date(YYYY-MM-GG HH:MM:SS)",
"title": "photo title",
"desc": "photo description",
"album": "album name",
"filename": "original file name",
"type": "mime type",
"height": "number",
"width": "number",
"profile": "1 if is profile photo",
"link": {
"<scale>": "url to image"
...
},
// if 'scale' is set
"datasize": "size in byte",
"data": "base64 encoded image data"
}
```
xml
```
<photo>
<id>photo id</id>
<created>date(YYYY-MM-GG HH:MM:SS)</created>
<edited>date(YYYY-MM-GG HH:MM:SS)</edited>
<title>photo title</title>
<desc>photo description</desc>
<album>album name</album>
<filename>original file name</filename>
<type>mime type</type>
<height>number</height>
<width>number</width>
<profile>1 if is profile photo</profile>
<links type="array">
<link type="mime type" scale="scale number" href="image url"/>
...
</links>
</photo>
```
---
### friendica/photos/list (*; AUTH)
Returns a list of all photo resources of the logged in user.
#### Return values
json
```
[
{
id: "resource_id",
album: "album name",
filename: "original file name",
type: "image mime type",
thumb: "url to thumb sized image"
},
...
]
```
xml
```
<photos type="array">
<photo id="resource_id"
album="album name"
filename="original file name"
type="image mime type">
"url to thumb sized image"
</photo>
...
</photos>
```
--- ---
## Not Implemented API calls ## Not Implemented API calls
The following API calls are implemented in GNU Social but not in Friendica: (incomplete) The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
@ -702,13 +778,13 @@ The following API calls from the Twitter API aren't implemented neither in Frien
### BASH / cURL ### BASH / cURL
Betamax has documentated some example API usage from a [bash script](https://en.wikipedia.org/wiki/Bash_(Unix_shell) employing [curl](https://en.wikipedia.org/wiki/CURL) (see [his posting](https://betamax65.de/display/betamax65/43539)). Betamax has documentated some example API usage from a [bash script](https://en.wikipedia.org/wiki/Bash_(Unix_shell) employing [curl](https://en.wikipedia.org/wiki/CURL) (see [his posting](https://betamax65.de/display/betamax65/43539)).
/usr/bin/curl -u USER:PASS https://YOUR.FRIENDICA.TLD/api/statuses/update.xml -d source="some source id" -d status="the status you want to post" /usr/bin/curl -u USER:PASS https://YOUR.FRIENDICA.TLD/api/statuses/update.xml -d source="some source id" -d status="the status you want to post"
### Python ### Python
The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python. The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following. The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python. The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
def tweet(server, message, group_allow=None): def tweet(server, message, group_allow=None):
url = server + '/api/statuses/update' url = server + '/api/statuses/update'
urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True)) urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API. There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.