keith/friendica
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update API docs

Browse source
This commit is contained in:
fabrixxm 2015-12-28 09:47:51 +01:00
parent 696fe53d8f
commit e752d41389
1 changed files with 239 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

195
doc/api.md
View file

@ -24,13 +24,45 @@ Please refer to the linked documentation for further information.
* cid: Contact id of the user (important for "contact_allow" and "contact_deny")
* network: network of the user
#### Errors
When an error occour in API call, an HTTP error code is returned, with an error message
Usually:
- 400 Bad Request: if parameter are missing or items can't be found
- 403 Forbidden: if authenticated user is missing
- 405 Method Not Allowed: if API was called with invalid method, eg. GET when API require POST
- 501 Not Implemented: if requested API doesn't exists
- 500 Internal Server Error: on other error contitions
Error body is
json:
```
{
"error": "Specific error message",
"request": "API path requested",
"code": "HTTP error code"
}
```
xml:
```
<status>
<error>Specific error message</error>
<request>API path requested</request>
<code>HTTP error code</code>
</status>
```
---
### account/rate_limit_status
---
### account/verify_credentials
#### Parameters
* skip_status: Don't show the "status" field. (Default: false)
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### conversation/show
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.
@ -47,6 +79,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
* trim_user
* contributor_details
---
### direct_messages
#### Parameters
* count: Items per page (default: 20)
@ -59,6 +92,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
#### Unsupported parameters
* skip_status
---
### direct_messages/all
#### Parameters
* count: Items per page (default: 20)
@ -67,6 +101,7 @@ Unofficial Twitter command. It shows all direct answers (excluding the original
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
---
### direct_messages/conversation
Shows all direct messages of a conversation
#### Parameters
@ -77,6 +112,7 @@ Shows all direct messages of a conversation
* getText: Defines the format of the status field. Can be "html" or "plain"
* uri: URI of the conversation
---
### direct_messages/new
#### Parameters
* user_id: id of the user
@ -85,6 +121,7 @@ Shows all direct messages of a conversation
* replyto: ID of the replied direct message
* title: Title of the direct message
---
### direct_messages/sent
#### Parameters
* count: Items per page (default: 20)
@ -94,6 +131,7 @@ Shows all direct messages of a conversation
* getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### favorites
#### Parameters
* count: Items per page (default: 20)
@ -108,16 +146,19 @@ Shows all direct messages of a conversation
Favorites aren't displayed to other users, so "user_id" and "screen_name". So setting this value will result in an empty array.
---
### favorites/create
#### Parameters
* id
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### favorites/destroy
#### Parameters
* id
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### followers/ids
#### Parameters
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
@ -129,16 +170,139 @@ 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/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/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
* stringify_ids: Should the id numbers be sent as text (true) or number (false)? (default: false)
@ -150,12 +314,15 @@ Returns a list of all photo resources of the logged in user.
Friendica doesn't allow showing friends of other users.
---
### help/test
---
### media/upload
#### Parameters
* media: image data
---
### oauth/request_token
#### Parameters
* oauth_callback
@ -163,6 +330,7 @@ Friendica doesn't allow showing friends of other users.
#### Unsupported parameters
* x_auth_access_type
---
### oauth/access_token
#### Parameters
* oauth_verifier
@ -172,6 +340,7 @@ Friendica doesn't allow showing friends of other users.
* x_auth_username
* x_auth_mode
---
### statuses/destroy
#### Parameters
* id: message number
@ -180,12 +349,15 @@ Friendica doesn't allow showing friends of other users.
#### Unsupported parameters
* trim_user
---
### statuses/followers
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### statuses/friends
* include_entities: "true" shows entities for pictures and links (Default: false)
---
### statuses/friends_timeline
#### Parameters
* count: Items per page (default: 20)
@ -201,6 +373,7 @@ Friendica doesn't allow showing friends of other users.
* trim_user
* contributor_details
---
### statuses/home_timeline
#### Parameters
* count: Items per page (default: 20)
@ -216,6 +389,7 @@ Friendica doesn't allow showing friends of other users.
* trim_user
* contributor_details
---
### statuses/mentions
#### Parameters
* count: Items per page (default: 20)
@ -229,6 +403,7 @@ Friendica doesn't allow showing friends of other users.
* trim_user
* contributor_details
---
### statuses/public_timeline
#### Parameters
* count: Items per page (default: 20)
@ -242,6 +417,7 @@ Friendica doesn't allow showing friends of other users.
#### Unsupported parameters
* trim_user
---
### statuses/replies
#### Parameters
* count: Items per page (default: 20)
@ -255,6 +431,7 @@ Friendica doesn't allow showing friends of other users.
* trim_user
* contributor_details
---
### statuses/retweet
#### Parameters
* id: message number
@ -263,6 +440,7 @@ Friendica doesn't allow showing friends of other users.
#### Unsupported parameters
* trim_user
---
### statuses/show
#### Parameters
* id: message number
@ -273,6 +451,7 @@ Friendica doesn't allow showing friends of other users.
* include_my_retweet
* trim_user
---
### statuses/update, statuses/update_with_media
#### Parameters
* title: Title of the status
@ -296,6 +475,7 @@ Friendica doesn't allow showing friends of other users.
* place_id
* display_coordinates
---
### statuses/user_timeline
#### Parameters
* user_id: id of the user
@ -313,8 +493,10 @@ Friendica doesn't allow showing friends of other users.
* trim_user
* contributor_details
---
### statusnet/config
---
### statusnet/version
#### Unsupported parameters
@ -324,6 +506,7 @@ Friendica doesn't allow showing friends of other users.
Friendica doesn't allow showing followers of other users.
---
### users/search
#### Parameters
* q: name of the user
@ -333,6 +516,7 @@ Friendica doesn't allow showing followers of other users.
* count
* include_entities
---
### users/show
#### Parameters
* user_id: id of the user
@ -349,6 +533,7 @@ Friendica doesn't allow showing friends of other users.
## Implemented API calls (not compatible with other APIs)
---
### friendica/group_show
Return all or a specified group of the user with the containing contacts as array.
@ -362,9 +547,11 @@ Array of:
* user: array of group members (return from api_get_user() function for each member)
---
### friendica/group_delete
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
@ -378,6 +565,7 @@ Array of:
* wrong users: empty array
---
### friendica/group_create
Create the group with the posted array of contacts as members.
#### Parameters
@ -398,6 +586,7 @@ Array of:
* wrong users: array of users, which were not available in the contact table
---
### friendica/group_update
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
@ -418,7 +607,7 @@ Array of:
* status: „missing user“ | „ok“
* wrong users: array of users, which were not available in the contact table
---
## Not Implemented API calls
The following API calls are implemented in GNU Social but not in Friendica: (incomplete)
@ -505,6 +694,10 @@ The following API calls from the Twitter API aren't implemented neither in Frien
* trends/closest
* users/report_spam
---
---
## Usage Examples
### 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)).