Lint doc/api.md
This commit is contained in:
Pierre Rudloff
parent
256bf2e888
commit
cf063b2045
1 changed files with 259 additions and 45 deletions
304
doc/api.md
304
doc/api.md
|
|
@ -1,5 +1,6 @@
|
|||
Friendica API
|
||||
===
|
||||
# Friendica API
|
||||
|
||||
<!-- markdownlint-disable MD010 MD013 MD024 -->
|
||||
|
||||
* [Home](help)
|
||||
|
||||
|
|
@ -10,6 +11,7 @@ Please refer to the linked documentation for further information.
|
|||
## Implemented API calls
|
||||
|
||||
### General
|
||||
|
||||
#### HTTP Method
|
||||
|
||||
API endpoints can restrict the method used to request them.
|
||||
|
|
@ -26,6 +28,7 @@ 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
|
||||
|
||||
* cursor: Not implemented in GNU Social
|
||||
* trim_user: Not implemented in GNU Social
|
||||
* contributor_details: Not implemented in GNU Social
|
||||
|
|
@ -35,26 +38,31 @@ In this document, endpoints which requires auth are marked with "AUTH" after end
|
|||
* include_my_retweet: Retweets in Friendica are implemented in a different way
|
||||
|
||||
#### Different behaviour
|
||||
|
||||
* screen_name: The nick name in friendica is only unique in each network but not for all networks. The users are searched in the following priority: Friendica, StatusNet/GNU Social, Diaspora, pump.io, Twitter. If no contact was found by this way, then the first contact is taken.
|
||||
* include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.
|
||||
|
||||
#### Return values
|
||||
|
||||
* cid: Contact id of the user (important for "contact_allow" and "contact_deny")
|
||||
* network: network of the user
|
||||
|
||||
#### Errors
|
||||
|
||||
When an error occurs in API call, an HTTP error code is returned, with an error message
|
||||
Usually:
|
||||
- 400 Bad Request: if parameters are missing or items can't be found
|
||||
- 403 Forbidden: if the authenticated user is missing
|
||||
- 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
|
||||
- 501 Not Implemented: if the requested API doesn't exist
|
||||
- 500 Internal Server Error: on other error conditions
|
||||
|
||||
* 400 Bad Request: if parameters are missing or items can't be found
|
||||
* 403 Forbidden: if the authenticated user is missing
|
||||
* 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
|
||||
* 501 Not Implemented: if the requested API doesn't exist
|
||||
* 500 Internal Server Error: on other error conditions
|
||||
|
||||
Error body is
|
||||
|
||||
json:
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Specific error message",
|
||||
"request": "API path requested",
|
||||
|
|
@ -63,7 +71,8 @@ json:
|
|||
```
|
||||
|
||||
xml:
|
||||
```
|
||||
|
||||
```xml
|
||||
<status>
|
||||
<error>Specific error message</error>
|
||||
<request>API path requested</request>
|
||||
|
|
@ -72,20 +81,26 @@ xml:
|
|||
```
|
||||
|
||||
---
|
||||
|
||||
### account/rate_limit_status (*; AUTH)
|
||||
|
||||
---
|
||||
|
||||
### account/verify_credentials (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* skip_status: Don't show the "status" field. (Default: false)
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
---
|
||||
|
||||
### conversation/show (*; AUTH)
|
||||
|
||||
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
|
||||
|
||||
#### Parameter
|
||||
|
||||
* id: id of the post
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
|
|
@ -94,13 +109,17 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
---
|
||||
|
||||
### direct_messages (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -110,11 +129,15 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
|
|||
* friendica_verbose: "true" enables different error returns (default: "false")
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* skip_status
|
||||
|
||||
---
|
||||
|
||||
### direct_messages/all (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -123,9 +146,13 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
|
|||
* friendica_verbose: "true" enables different error returns (default: "false")
|
||||
|
||||
---
|
||||
|
||||
### direct_messages/conversation (*; AUTH)
|
||||
|
||||
Shows all direct messages of a conversation
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -135,8 +162,11 @@ Shows all direct messages of a conversation
|
|||
* friendica_verbose: "true" enables different error returns (default: "false")
|
||||
|
||||
---
|
||||
|
||||
### direct_messages/sent (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -146,8 +176,11 @@ Shows all direct messages of a conversation
|
|||
* friendica_verbose: "true" enables different error returns (default: "false")
|
||||
|
||||
---
|
||||
|
||||
### direct_messages/new (POST,PUT; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* user_id: id of the user
|
||||
* screen_name: screen name (for technical reasons, this value is not unique!)
|
||||
* text: The message
|
||||
|
|
@ -155,8 +188,11 @@ Shows all direct messages of a conversation
|
|||
* title: Title of the direct message
|
||||
|
||||
---
|
||||
|
||||
### direct_messages/destroy (POST,DELETE; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* id: id of the message to be deleted
|
||||
* include_entities: optional, currently not yet implemented
|
||||
* friendica_parenturi: optional, can be used for increased safety to delete only intended messages
|
||||
|
|
@ -165,21 +201,29 @@ Shows all direct messages of a conversation
|
|||
#### Return values
|
||||
|
||||
On success:
|
||||
|
||||
* JSON return as defined for Twitter API not yet implemented
|
||||
* on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}
|
||||
|
||||
On error:
|
||||
HTTP 400 BadRequest
|
||||
|
||||
* on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"}
|
||||
|
||||
---
|
||||
|
||||
### externalprofile/show (*)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* profileurl: profile url
|
||||
|
||||
---
|
||||
|
||||
### favorites (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -187,6 +231,7 @@ HTTP 400 BadRequest
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* user_id
|
||||
* screen_name
|
||||
|
||||
|
|
@ -194,23 +239,33 @@ Favorites aren't displayed to other users, so "user_id" and "screen_name" are un
|
|||
Set this values will result in an empty array.
|
||||
|
||||
---
|
||||
|
||||
### favorites/create (POST,PUT; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* id
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
---
|
||||
|
||||
### favorites/destroy (POST,DELETE; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* id
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
---
|
||||
|
||||
### followers/ids (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* stringify_ids: Send id numbers as text (true) or integers (false)? (default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* user_id
|
||||
* screen_name
|
||||
* cursor
|
||||
|
|
@ -218,11 +273,15 @@ Set this values will result in an empty array.
|
|||
Friendica doesn't allow showing the followers of other users.
|
||||
|
||||
---
|
||||
|
||||
### friends/ids (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* stringify_ids: Send the id numbers as text (true) or integers (false)? (default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* user_id
|
||||
* screen_name
|
||||
* cursor
|
||||
|
|
@ -230,41 +289,58 @@ Friendica doesn't allow showing the followers of other users.
|
|||
Friendica doesn't allow showing the friends of other users.
|
||||
|
||||
---
|
||||
|
||||
### help/test (*)
|
||||
|
||||
---
|
||||
|
||||
### media/upload (POST,PUT; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* media: image data
|
||||
|
||||
---
|
||||
|
||||
### oauth/request_token (*)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* oauth_callback
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* x_auth_access_type
|
||||
|
||||
---
|
||||
|
||||
### oauth/access_token (*)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* oauth_verifier
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* x_auth_password
|
||||
* x_auth_username
|
||||
* x_auth_mode
|
||||
|
||||
---
|
||||
|
||||
### statuses/destroy (POST,DELETE; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* id: message number
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* trim_user
|
||||
|
||||
---
|
||||
|
||||
### statuses/followers (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
|
@ -272,6 +348,7 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
---
|
||||
|
||||
### statuses/friends (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
|
@ -279,6 +356,7 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
---
|
||||
|
||||
### blocks/list (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
|
@ -288,12 +366,16 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* page: page number
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* cursor
|
||||
* skip_status
|
||||
|
||||
---
|
||||
|
||||
### statuses/friends_timeline (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -303,13 +385,17 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
---
|
||||
|
||||
### statuses/home_timeline (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -319,13 +405,17 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
---
|
||||
|
||||
### statuses/mentions (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -333,13 +423,17 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
---
|
||||
|
||||
### statuses/public_timeline (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -349,11 +443,15 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* trim_user
|
||||
|
||||
---
|
||||
|
||||
### statuses/networkpublic_timeline (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -361,8 +459,11 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
---
|
||||
|
||||
### statuses/replies (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
* since_id: minimum id
|
||||
|
|
@ -370,33 +471,45 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* include_rts
|
||||
* trim_user
|
||||
* contributor_details
|
||||
|
||||
---
|
||||
|
||||
### statuses/retweet (POST,PUT; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* id: message number
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* trim_user
|
||||
|
||||
---
|
||||
|
||||
### statuses/show (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* id: message number
|
||||
* conversation: if set to "1" show all messages of the conversation with the given id
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* include_my_retweet
|
||||
* trim_user
|
||||
|
||||
---
|
||||
|
||||
### statuses/update, statuses/update_with_media
|
||||
|
||||
#### Parameters
|
||||
|
||||
* title: Title of the status
|
||||
* status: Status in text format
|
||||
* htmlstatus: Status in HTML format
|
||||
|
|
@ -414,13 +527,17 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* media_ids: (By now only a single value, no array)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* trim_user
|
||||
* place_id
|
||||
* display_coordinates
|
||||
|
||||
---
|
||||
|
||||
### statuses/user_timeline (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* user_id: id of the user
|
||||
* screen_name: screen name (for technical reasons, this value is not unique!)
|
||||
* count: Items per page (default: 20)
|
||||
|
|
@ -438,13 +555,17 @@ Friendica doesn't allow showing the friends of other users.
|
|||
* contributor_details
|
||||
|
||||
---
|
||||
|
||||
### statusnet/config (*)
|
||||
|
||||
---
|
||||
|
||||
### statusnet/conversation (*; AUTH)
|
||||
|
||||
It shows all direct answers (excluding the original post) to a given id.
|
||||
|
||||
#### Parameter
|
||||
|
||||
* id: id of the post
|
||||
* count: Items per page (default: 20)
|
||||
* page: page number
|
||||
|
|
@ -453,9 +574,11 @@ It shows all direct answers (excluding the original post) to a given id.
|
|||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
---
|
||||
|
||||
### statusnet/version (*)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* user_id
|
||||
* screen_name
|
||||
* cursor
|
||||
|
|
@ -463,8 +586,11 @@ It shows all direct answers (excluding the original post) to a given id.
|
|||
Friendica doesn't allow showing followers of other users.
|
||||
|
||||
---
|
||||
|
||||
### search (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* q: search query
|
||||
* page: the page number (starting at 1) to return
|
||||
* rpp: the number of statuses to return per page
|
||||
|
|
@ -473,6 +599,7 @@ Friendica doesn't allow showing followers of other users.
|
|||
* max_id: returns statuses with ids lower or equal to the given id
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* geocode
|
||||
* lang
|
||||
* locale
|
||||
|
|
@ -481,23 +608,31 @@ Friendica doesn't allow showing followers of other users.
|
|||
* include_entities
|
||||
|
||||
---
|
||||
|
||||
### users/search (*)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* q: name of the user
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* page
|
||||
* count
|
||||
* include_entities
|
||||
|
||||
---
|
||||
|
||||
### users/show (*)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* user_id: id of the user
|
||||
* screen_name: screen name (for technical reasons, this value is not unique!)
|
||||
* include_entities: "true" shows entities for pictures and links (Default: false)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* user_id
|
||||
* screen_name
|
||||
* cursor
|
||||
|
|
@ -505,18 +640,24 @@ Friendica doesn't allow showing followers of other users.
|
|||
Friendica doesn't allow showing friends of other users.
|
||||
|
||||
---
|
||||
|
||||
### users/lookup (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* user_id: list of ids to lookup
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* screen_name
|
||||
* include_entities
|
||||
|
||||
---
|
||||
|
||||
### account/update_profile_image (POST; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more)
|
||||
* profile_id (optional): id of the profile for which the image should be used, default is changing the default profile
|
||||
|
||||
|
|
@ -525,9 +666,11 @@ uploads a new profile image (scales 4-6) to database, changes default or specifi
|
|||
#### Return values
|
||||
|
||||
On success:
|
||||
|
||||
* JSON return: returns the updated user details (see account/verify_credentials)
|
||||
|
||||
On error:
|
||||
|
||||
* 403 FORBIDDEN: if not authenticated
|
||||
* 400 BADREQUEST: "no media data submitted", "profile_id not available"
|
||||
* 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
|
||||
|
|
@ -535,23 +678,33 @@ On error:
|
|||
"unable to process image data",
|
||||
"image upload failed"
|
||||
|
||||
---
|
||||
|
||||
### friendships/incoming (*; AUTH)
|
||||
|
||||
#### Unsupported parameters
|
||||
|
||||
* cursor
|
||||
* stringify_ids
|
||||
|
||||
## Implemented API calls (not compatible with other APIs)
|
||||
|
||||
|
||||
---
|
||||
### friendica/activity/<verb>
|
||||
|
||||
### 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
|
||||
* 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".
|
||||
|
|
@ -560,39 +713,48 @@ Attend verbs should be used only with event-related items (there is no check at
|
|||
#### Return values
|
||||
|
||||
On success:
|
||||
json
|
||||
json:
|
||||
|
||||
```"ok"```
|
||||
|
||||
xml
|
||||
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.
|
||||
|
||||
#### Parameters
|
||||
|
||||
* gid: optional, if not given, API returns all groups of the user
|
||||
|
||||
#### Return values
|
||||
|
||||
Array of:
|
||||
|
||||
* name: name of the group
|
||||
* gid: id of the group
|
||||
* user: array of group members (return from api_get_user() function for each member)
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
|
||||
#### Parameters
|
||||
|
||||
* gid: id of the group to be deleted
|
||||
* name: name of the group to be deleted
|
||||
|
||||
#### Return values
|
||||
|
||||
Array of:
|
||||
|
||||
* success: true if successfully deleted
|
||||
|
|
@ -601,15 +763,18 @@ Array of:
|
|||
* status: „deleted“ if successfully deleted
|
||||
* wrong users: empty array
|
||||
|
||||
|
||||
---
|
||||
|
||||
### friendica/group_create (POST,PUT; AUTH)
|
||||
|
||||
Create the group with the posted array of contacts as members.
|
||||
|
||||
#### Parameters
|
||||
|
||||
* name: name of the group to be created
|
||||
|
||||
#### POST data
|
||||
|
||||
JSON data as Array like the result of "users/group_show":
|
||||
|
||||
* gid
|
||||
|
|
@ -617,6 +782,7 @@ JSON data as Array like the result of "users/group_show":
|
|||
* array of users
|
||||
|
||||
#### Return values
|
||||
|
||||
Array of:
|
||||
|
||||
* success: true if successfully created or reactivated
|
||||
|
|
@ -625,16 +791,19 @@ Array of:
|
|||
* status: „missing user“ | „reactivated“ | „ok“
|
||||
* wrong users: array of users, which were not available in the contact table
|
||||
|
||||
|
||||
---
|
||||
|
||||
### 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).
|
||||
|
||||
#### Parameters
|
||||
|
||||
* gid: id of the group to be changed
|
||||
* name: name of the group to be changed
|
||||
|
||||
#### POST data
|
||||
|
||||
JSON data as array like the result of „users/group_show“:
|
||||
|
||||
* gid
|
||||
|
|
@ -642,6 +811,7 @@ JSON data as array like the result of „users/group_show“:
|
|||
* array of users
|
||||
|
||||
#### Return values
|
||||
|
||||
Array of:
|
||||
|
||||
* success: true if successfully updated
|
||||
|
|
@ -650,16 +820,18 @@ Array of:
|
|||
* status: „missing user“ | „ok“
|
||||
* 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
|
||||
|
|
@ -676,25 +848,30 @@ Array of:
|
|||
* 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) | <status>success</status>;" (xml)
|
||||
|
||||
* `success` (json) | `<status>success</status>` (xml)
|
||||
|
||||
---
|
||||
|
||||
### friendica/photo (*; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* photo_id: Resource id of a photo.
|
||||
* scale: (optional) scale value of the photo
|
||||
|
||||
|
|
@ -716,8 +893,9 @@ An image used as profile image has only scale 4-6, other images only 0-3
|
|||
|
||||
#### Return values
|
||||
|
||||
json
|
||||
```
|
||||
json:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "photo id"
|
||||
"created": "date(YYYY-MM-DD HH:MM:SS)",
|
||||
|
|
@ -740,8 +918,9 @@ json
|
|||
}
|
||||
```
|
||||
|
||||
xml
|
||||
```
|
||||
xml:
|
||||
|
||||
```xml
|
||||
<photo>
|
||||
<id>photo id</id>
|
||||
<created>date(YYYY-MM-DD HH:MM:SS)</created>
|
||||
|
|
@ -762,14 +941,16 @@ xml
|
|||
```
|
||||
|
||||
---
|
||||
|
||||
### friendica/photos/list (*; AUTH)
|
||||
|
||||
Returns a list of all photo resources of the logged in user.
|
||||
|
||||
#### Return values
|
||||
|
||||
json
|
||||
```
|
||||
json:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
id: "resource_id",
|
||||
|
|
@ -782,8 +963,9 @@ json
|
|||
]
|
||||
```
|
||||
|
||||
xml
|
||||
```
|
||||
xml:
|
||||
|
||||
```xml
|
||||
<photos type="array">
|
||||
<photo id="resource_id"
|
||||
album="album name"
|
||||
|
|
@ -796,8 +978,11 @@ xml
|
|||
```
|
||||
|
||||
---
|
||||
|
||||
### friendica/photoalbum/delete (POST,DELETE; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* album: name of the album to be deleted
|
||||
|
||||
deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this
|
||||
|
|
@ -805,17 +990,21 @@ deletes all images with the specified album name, is not reversible -> ensure th
|
|||
#### Return values
|
||||
|
||||
On success:
|
||||
|
||||
* JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."}
|
||||
|
||||
On error:
|
||||
|
||||
* 403 FORBIDDEN: if not authenticated
|
||||
* 400 BADREQUEST: "no albumname specified", "album not available"
|
||||
* 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed"
|
||||
|
||||
|
||||
---
|
||||
|
||||
### friendica/photoalbum/update (POST,PUT; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* album: name of the album to be updated
|
||||
* album_new: new name of the album
|
||||
|
||||
|
|
@ -824,18 +1013,23 @@ changes the album name to album_new for all photos in album
|
|||
#### Return values
|
||||
|
||||
On success:
|
||||
|
||||
* JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."}
|
||||
|
||||
On error:
|
||||
|
||||
* 403 FORBIDDEN: if not authenticated
|
||||
* 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available"
|
||||
* 500 INTERNALSERVERERROR: "unknown error - updating in database failed"
|
||||
|
||||
|
||||
---
|
||||
|
||||
### friendica/photo/create (POST; AUTH)
|
||||
|
||||
### friendica/photo/update (POST; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* photo_id (optional): if specified the photo with this id will be updated
|
||||
* media (optional): image data as base64, only optional if photo_id is specified (new upload must have media)
|
||||
* desc (optional): description for the photo, updated when photo_id is specified
|
||||
|
|
@ -853,12 +1047,14 @@ Currently it is best to inform user that updating rights is not the right way to
|
|||
#### Return values
|
||||
|
||||
On success:
|
||||
|
||||
* new photo uploaded: JSON return with photo data (see friendica/photo)
|
||||
* photo updated - changed photo data: JSON return with photo data (see friendica/photo)
|
||||
* photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."}
|
||||
* photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."}
|
||||
|
||||
On error:
|
||||
|
||||
* 403 FORBIDDEN: if not authenticated
|
||||
* 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid"
|
||||
* 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server",
|
||||
|
|
@ -869,10 +1065,12 @@ On error:
|
|||
"unknown error - update photo entry in database failed",
|
||||
"unknown error - this error on uploading or updating a photo should never happen"
|
||||
|
||||
|
||||
---
|
||||
|
||||
### friendica/photo/delete (DELETE; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* photo_id: id of the photo to be deleted
|
||||
|
||||
deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this
|
||||
|
|
@ -881,50 +1079,66 @@ Sets item table entries for this photo to deleted = 1
|
|||
#### Return values
|
||||
|
||||
On success:
|
||||
|
||||
* JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."}
|
||||
|
||||
On error:
|
||||
|
||||
* 403 FORBIDDEN: if not authenticated
|
||||
* 400 BADREQUEST: "no photo_id specified", "photo not available"
|
||||
* 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred"
|
||||
|
||||
|
||||
---
|
||||
|
||||
### friendica/direct_messages_setseen (GET; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* id: id of the message to be updated as seen
|
||||
|
||||
#### Return values
|
||||
|
||||
On success:
|
||||
|
||||
* JSON return {"result":"ok","message":"message set to seen"}
|
||||
|
||||
On error:
|
||||
|
||||
* different JSON returns {"result":"error","message":"xyz"}
|
||||
|
||||
---
|
||||
|
||||
### friendica/direct_messages_search (GET; AUTH)
|
||||
|
||||
#### Parameters
|
||||
|
||||
* searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored)
|
||||
|
||||
#### Return values
|
||||
|
||||
Returns only tested with JSON, XML might work as well.
|
||||
|
||||
On success:
|
||||
|
||||
* JSON return {"success":"true","search_results": array of found messages}
|
||||
* JSOn return {"success":"false","search_results":"nothing found"}
|
||||
|
||||
On error:
|
||||
|
||||
* different JSON returns {"result":"error","message":"searchstring not specified"}
|
||||
|
||||
---
|
||||
|
||||
### friendica/profile/show (GET; AUTH)
|
||||
|
||||
show data of all profiles or a single profile of the authenticated user
|
||||
|
||||
#### Parameters
|
||||
|
||||
* profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default)
|
||||
|
||||
#### Return values
|
||||
|
||||
On success: Array of:
|
||||
|
||||
* multi_profiles: true if user has activated multi_profiles
|
||||
|
|
@ -937,6 +1151,7 @@ HTTP 403 Forbidden: when no authentication was provided
|
|||
HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user
|
||||
|
||||
General description of profile data in API returns:
|
||||
|
||||
* profile_id
|
||||
* profile_name
|
||||
* is_default: true if this is the public profile
|
||||
|
|
@ -949,14 +1164,9 @@ General description of profile data in API returns:
|
|||
* users: array with the users allowed to view this profile (empty if is_default=true)
|
||||
|
||||
---
|
||||
### friendships/incoming (*; AUTH)
|
||||
|
||||
#### Unsupported parameters
|
||||
* cursor
|
||||
* stringify_ids
|
||||
|
||||
---
|
||||
## Not Implemented API calls
|
||||
|
||||
The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
|
||||
|
||||
* statuses/retweets_of_me
|
||||
|
|
@ -1041,12 +1251,16 @@ The following API calls from the Twitter API are not implemented in either Frien
|
|||
---
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### BASH / cURL
|
||||
|
||||
```bash
|
||||
/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
|
||||
The [RSStoFriedika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
|
||||
|
||||
The [RSStoFriendika](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):
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue