## Implemented API calls\r
\r
### General\r
+#### HTTP Method\r
+\r
+API endpoints can restrict the method used to request them.\r
+Using an invalid method results in HTTP error 405 "Method Not Allowed".\r
+\r
+In this document, the required method is listed after the endpoint name. "*" means every method can be used.\r
+\r
+#### Auth\r
+\r
+Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.\r
+\r
+OAuth settings can be added by the user in web UI under /settings/oauth/\r
+\r
+In this document, endpoints which requires auth are marked with "AUTH" after endpoint name\r
+\r
#### Unsupported parameters\r
* cursor: Not implemented in GNU Social\r
* trim_user: Not implemented in GNU Social\r
\r
json:\r
```\r
- {\r
- "error": "Specific error message",\r
- "request": "API path requested",\r
- "code": "HTTP error code"\r
- }\r
+{\r
+"error": "Specific error message",\r
+"request": "API path requested",\r
+"code": "HTTP error code"\r
+}\r
```\r
\r
xml:\r
```\r
- <status>\r
- <error>Specific error message</error>\r
- <request>API path requested</request>\r
- <code>HTTP error code</code>\r
- </status>\r
+<status>\r
+<error>Specific error message</error>\r
+<request>API path requested</request>\r
+<code>HTTP error code</code>\r
+</status>\r
```\r
\r
---\r
-### account/rate_limit_status\r
+### account/rate_limit_status (*; AUTH)\r
\r
---\r
-### account/verify_credentials\r
+### account/verify_credentials (*; AUTH)\r
#### Parameters\r
+\r
* skip_status: Don't show the "status" field. (Default: false)\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
\r
---\r
-### conversation/show\r
+### conversation/show (*; AUTH)\r
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.\r
\r
-#### Parameters\r
+#### Parameter\r
* id: id of the post\r
* count: Items per page (default: 20)\r
* page: page number\r
* contributor_details\r
\r
---\r
-### direct_messages\r
+### direct_messages (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* skip_status\r
\r
---\r
-### direct_messages/all\r
+### direct_messages/all (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* getText: Defines the format of the status field. Can be "html" or "plain"\r
\r
---\r
-### direct_messages/conversation\r
+### direct_messages/conversation (*; AUTH)\r
Shows all direct messages of a conversation\r
#### Parameters\r
* count: Items per page (default: 20)\r
* uri: URI of the conversation\r
\r
---\r
-### direct_messages/new\r
+### direct_messages/new (POST,PUT; AUTH)\r
#### Parameters\r
* user_id: id of the user\r
* screen_name: screen name (for technical reasons, this value is not unique!)\r
* title: Title of the direct message\r
\r
---\r
-### direct_messages/sent\r
+### direct_messages/sent (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
\r
---\r
-### favorites\r
+### favorites (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* user_id\r
* screen_name\r
\r
-Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array.\r
+Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported.\r
+Set this values will result in an empty array.\r
\r
---\r
-### favorites/create\r
+### favorites/create (POST,PUT; AUTH)\r
#### Parameters\r
* id\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
\r
---\r
-### favorites/destroy\r
+### favorites/destroy (POST,DELETE; AUTH)\r
#### Parameters\r
* id\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
\r
---\r
-### followers/ids\r
+### followers/ids (*; AUTH)\r
#### Parameters\r
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
\r
Friendica doesn't allow showing followers of other users.\r
\r
---\r
-### friendica/activity/<verb>\r
-#### parameters\r
-* id: item id\r
-\r
-Add or remove an activity from an item.\r
-'verb' can be one of:\r
-- like\r
-- dislike\r
-- attendyes\r
-- attendno\r
-- attendmaybe\r
-\r
-To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"\r
-Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".\r
-Attend verbs should be used only with event-related items (there is no check at the moment)\r
-\r
-#### Return values\r
-\r
-On success:\r
-json\r
-```"ok"```\r
-\r
-xml\r
-```<ok>true</ok>```\r
-\r
-On error:\r
-HTTP 400 BadRequest\r
-\r
----\r
-### friendica/photo\r
-#### Parameters\r
-* photo_id: Resource id of a photo.\r
-* scale: (optional) scale value of the photo\r
-\r
-Returns data of a picture with the given resource.\r
-If 'scale' isn't provided, returned data include full url to each scale of the photo.\r
-If 'scale' is set, returned data include image data base64 encoded.\r
-\r
-possibile scale value are:\r
-0: original or max size by server settings\r
-1: image with or height at <= 640\r
-2: image with or height at <= 320\r
-3: thumbnail 160x160\r
-\r
-4: Profile image at 175x175\r
-5: Profile image at 80x80\r
-6: Profile image at 48x48\r
-\r
-An image used as profile image has only scale 4-6, other images only 0-3\r
-\r
-#### Return values\r
-\r
-json\r
-```\r
- {\r
- "id": "photo id"\r
- "created": "date(YYYY-MM-GG HH:MM:SS)",\r
- "edited": "date(YYYY-MM-GG HH:MM:SS)",\r
- "title": "photo title",\r
- "desc": "photo description",\r
- "album": "album name",\r
- "filename": "original file name",\r
- "type": "mime type",\r
- "height": "number",\r
- "width": "number",\r
- "profile": "1 if is profile photo",\r
- "link": {\r
- "<scale>": "url to image"\r
- ...\r
- },\r
- // if 'scale' is set\r
- "datasize": "size in byte",\r
- "data": "base64 encoded image data"\r
- }\r
-```\r
-\r
-xml\r
-```\r
- <photo>\r
- <id>photo id</id>\r
- <created>date(YYYY-MM-GG HH:MM:SS)</created>\r
- <edited>date(YYYY-MM-GG HH:MM:SS)</edited>\r
- <title>photo title</title>\r
- <desc>photo description</desc>\r
- <album>album name</album>\r
- <filename>original file name</filename>\r
- <type>mime type</type>\r
- <height>number</height>\r
- <width>number</width>\r
- <profile>1 if is profile photo</profile>\r
- <links type="array">\r
- <link type="mime type" scale="scale number" href="image url"/>\r
- ...\r
- </links>\r
- </photo>\r
-```\r
-\r
----\r
-### friendica/photos/list\r
-\r
-Returns a list of all photo resources of the logged in user.\r
-\r
-#### Return values\r
-\r
-json\r
-```\r
- [\r
- {\r
- id: "resource_id",\r
- album: "album name",\r
- filename: "original file name",\r
- type: "image mime type",\r
- thumb: "url to thumb sized image"\r
- },\r
- ...\r
- ]\r
-```\r
-\r
-xml\r
-```\r
- <photos type="array">\r
- <photo id="resource_id"\r
- album="album name"\r
- filename="original file name"\r
- type="image mime type">\r
- "url to thumb sized image"\r
- </photo>\r
- ...\r
- </photos>\r
-```\r
-\r
----\r
-### friends/ids\r
+### friends/ids (*; AUTH)\r
#### Parameters\r
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)\r
\r
Friendica doesn't allow showing friends of other users.\r
\r
---\r
-### help/test\r
+### help/test (*)\r
\r
---\r
-### media/upload\r
+### media/upload (POST,PUT; AUTH)\r
#### Parameters\r
* media: image data\r
\r
---\r
-### oauth/request_token\r
+### oauth/request_token (*)\r
#### Parameters\r
* oauth_callback\r
\r
* x_auth_access_type\r
\r
---\r
-### oauth/access_token\r
+### oauth/access_token (*)\r
#### Parameters\r
* oauth_verifier\r
\r
* x_auth_mode\r
\r
---\r
-### statuses/destroy\r
+### statuses/destroy (POST,DELETE; AUTH)\r
#### Parameters\r
* id: message number\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
* trim_user\r
\r
---\r
-### statuses/followers\r
+### statuses/followers (*; AUTH)\r
+\r
+#### Parameters\r
+\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
\r
---\r
-### statuses/friends\r
+### statuses/friends (*; AUTH)\r
+\r
+#### Parameters\r
+\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
\r
---\r
-### statuses/friends_timeline\r
+### statuses/friends_timeline (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* contributor_details\r
\r
---\r
-### statuses/home_timeline\r
+### statuses/home_timeline (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* contributor_details\r
\r
---\r
-### statuses/mentions\r
+### statuses/mentions (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* contributor_details\r
\r
---\r
-### statuses/public_timeline\r
+### statuses/public_timeline (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* trim_user\r
\r
---\r
-### statuses/replies\r
+### statuses/replies (*; AUTH)\r
#### Parameters\r
* count: Items per page (default: 20)\r
* page: page number\r
* contributor_details\r
\r
---\r
-### statuses/retweet\r
+### statuses/retweet (POST,PUT; AUTH)\r
#### Parameters\r
* id: message number\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
* trim_user\r
\r
---\r
-### statuses/show\r
+### statuses/show (*; AUTH)\r
#### Parameters\r
* id: message number\r
* conversation: if set to "1" show all messages of the conversation with the given id\r
* display_coordinates\r
\r
---\r
-### statuses/user_timeline\r
+### statuses/user_timeline (*; AUTH)\r
#### Parameters\r
* user_id: id of the user\r
* screen_name: screen name (for technical reasons, this value is not unique!)\r
* include_entities: "true" shows entities for pictures and links (Default: false)\r
\r
#### Unsupported parameters\r
+\r
* include_rts\r
* trim_user\r
* contributor_details\r
\r
---\r
-### statusnet/config\r
+### statusnet/config (*)\r
\r
---\r
-### statusnet/version\r
+### statusnet/version (*)\r
\r
#### Unsupported parameters\r
* user_id\r
Friendica doesn't allow showing followers of other users.\r
\r
---\r
-### users/search\r
+### users/search (*)\r
#### Parameters\r
* q: name of the user\r
\r
* include_entities\r
\r
---\r
-### users/show\r
+### users/show (*)\r
#### Parameters\r
* user_id: id of the user\r
* screen_name: screen name (for technical reasons, this value is not unique!)\r
\r
## Implemented API calls (not compatible with other APIs)\r
\r
+\r
---\r
-### friendica/group_show\r
+### friendica/activity/<verb>\r
+#### parameters\r
+* id: item id\r
+\r
+Add or remove an activity from an item.\r
+'verb' can be one of:\r
+\r
+- like\r
+- dislike\r
+- attendyes\r
+- attendno\r
+- attendmaybe\r
+\r
+To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike"\r
+Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes".\r
+Attend verbs should be used only with event-related items (there is no check at the moment)\r
+\r
+#### Return values\r
+\r
+On success:\r
+json\r
+```"ok"```\r
+\r
+xml\r
+```<ok>true</ok>```\r
+\r
+On error:\r
+HTTP 400 BadRequest\r
+\r
+---\r
+### friendica/group_show (*; AUTH)\r
Return all or a specified group of the user with the containing contacts as array.\r
\r
#### Parameters\r
\r
#### Return values\r
Array of:\r
+\r
* name: name of the group\r
* gid: id of the group\r
* user: array of group members (return from api_get_user() function for each member)\r
\r
\r
---\r
-### friendica/group_delete\r
+### friendica/group_delete (POST,DELETE; AUTH)\r
delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted.\r
\r
----\r
-### Parameters\r
+#### Parameters\r
* gid: id of the group to be deleted\r
* name: name of the group to be deleted\r
\r
#### Return values\r
Array of:\r
+\r
* success: true if successfully deleted\r
* gid: gid of the deleted group\r
* name: name of the deleted group\r
\r
\r
---\r
-### friendica/group_create\r
+### friendica/group_create (POST,PUT; AUTH)\r
Create the group with the posted array of contacts as members.\r
+\r
#### Parameters\r
* name: name of the group to be created\r
\r
#### POST data\r
-JSON data as Array like the result of „users/group_show“:\r
+JSON data as Array like the result of "users/group_show":\r
+\r
* gid\r
* name\r
* array of users\r
\r
#### Return values\r
Array of:\r
+\r
* success: true if successfully created or reactivated\r
* gid: gid of the created group\r
* name: name of the created group\r
\r
\r
---\r
-### friendica/group_update\r
+### friendica/group_update (POST)\r
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).\r
+\r
#### Parameters\r
* gid: id of the group to be changed\r
* name: name of the group to be changed\r
\r
#### POST data\r
JSON data as array like the result of „users/group_show“:\r
+\r
* gid\r
* name\r
* array of users\r
\r
#### Return values\r
Array of:\r
+\r
* success: true if successfully updated\r
* gid: gid of the changed group\r
* name: name of the changed group\r
* status: „missing user“ | „ok“\r
* wrong users: array of users, which were not available in the contact table\r
\r
+\r
+\r
+---\r
+### friendica/notifications (GET)\r
+Return last 50 notification for current user, ordered by date with unseen item on top\r
+\r
+#### Parameters\r
+none\r
+\r
+#### Return values\r
+Array of:\r
+\r
+* id: id of the note\r
+* type: type of notification as int (see NOTIFY_* constants in boot.php)\r
+* name: full name of the contact subject of the note\r
+* url: contact's profile url\r
+* photo: contact's profile photo\r
+* date: datetime string of the note\r
+* timestamp: timestamp of the node\r
+* date_rel: relative date of the note (eg. "1 hour ago")\r
+* msg: note message in bbcode\r
+* msg_html: note message in html\r
+* msg_plain: note message in plain text\r
+* link: link to note\r
+* seen: seen state: 0 or 1\r
+\r
+\r
+---\r
+### friendica/notifications/seen (POST)\r
+Set note as seen, returns item object if possible\r
+\r
+#### Parameters\r
+id: id of the note to set seen\r
+\r
+#### Return values\r
+If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api.\r
+\r
+If the note is not linked to an item, a success status is returned:\r
+\r
+* "success" (json) | "<status>success</status>" (xml)\r
+\r
+\r
+---\r
+### friendica/photo (*; AUTH)\r
+#### Parameters\r
+* photo_id: Resource id of a photo.\r
+* scale: (optional) scale value of the photo\r
+\r
+Returns data of a picture with the given resource.\r
+If 'scale' isn't provided, returned data include full url to each scale of the photo.\r
+If 'scale' is set, returned data include image data base64 encoded.\r
+\r
+possibile scale value are:\r
+\r
+* 0: original or max size by server settings\r
+* 1: image with or height at <= 640\r
+* 2: image with or height at <= 320\r
+* 3: thumbnail 160x160\r
+* 4: Profile image at 175x175\r
+* 5: Profile image at 80x80\r
+* 6: Profile image at 48x48\r
+\r
+An image used as profile image has only scale 4-6, other images only 0-3\r
+\r
+#### Return values\r
+\r
+json\r
+```\r
+{\r
+"id": "photo id"\r
+"created": "date(YYYY-MM-GG HH:MM:SS)",\r
+"edited": "date(YYYY-MM-GG HH:MM:SS)",\r
+"title": "photo title",\r
+"desc": "photo description",\r
+"album": "album name",\r
+"filename": "original file name",\r
+"type": "mime type",\r
+"height": "number",\r
+"width": "number",\r
+"profile": "1 if is profile photo",\r
+"link": {\r
+"<scale>": "url to image"\r
+...\r
+},\r
+// if 'scale' is set\r
+"datasize": "size in byte",\r
+"data": "base64 encoded image data"\r
+}\r
+```\r
+\r
+xml\r
+```\r
+<photo>\r
+<id>photo id</id>\r
+<created>date(YYYY-MM-GG HH:MM:SS)</created>\r
+<edited>date(YYYY-MM-GG HH:MM:SS)</edited>\r
+<title>photo title</title>\r
+<desc>photo description</desc>\r
+<album>album name</album>\r
+<filename>original file name</filename>\r
+<type>mime type</type>\r
+<height>number</height>\r
+<width>number</width>\r
+<profile>1 if is profile photo</profile>\r
+<links type="array">\r
+<link type="mime type" scale="scale number" href="image url"/>\r
+...\r
+</links>\r
+</photo>\r
+```\r
+\r
+---\r
+### friendica/photos/list (*; AUTH)\r
+\r
+Returns a list of all photo resources of the logged in user.\r
+\r
+#### Return values\r
+\r
+json\r
+```\r
+[\r
+{\r
+id: "resource_id",\r
+album: "album name",\r
+filename: "original file name",\r
+type: "image mime type",\r
+thumb: "url to thumb sized image"\r
+},\r
+...\r
+]\r
+```\r
+\r
+xml\r
+```\r
+<photos type="array">\r
+<photo id="resource_id"\r
+album="album name"\r
+filename="original file name"\r
+type="image mime type">\r
+"url to thumb sized image"\r
+</photo>\r
+...\r
+</photos>\r
+```\r
+\r
+\r
---\r
## Not Implemented API calls\r
The following API calls are implemented in GNU Social but not in Friendica: (incomplete)\r
### BASH / cURL\r
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)).\r
\r
- /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"\r
+/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"\r
\r
### Python\r
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.\r
\r
- def tweet(server, message, group_allow=None):\r
- url = server + '/api/statuses/update'\r
- urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))\r
+def tweet(server, message, group_allow=None):\r
+url = server + '/api/statuses/update'\r
+urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))\r
\r
There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.\r
projects / friendica.git / commitdiff