]> git.mxchange.org Git - friendica.git/blob - doc/api.md
Added documentation
[friendica.git] / doc / api.md
1 # Using the APIs
2
3 <!-- markdownlint-disable MD010 MD013 MD024 -->
4
5 * [Home](help)
6
7 Friendica offers multiple API endpoints to interface with third-party applications:
8
9 - [Twitter](help/API-Twitter)
10 - [Mastodon](help/API-Mastodon)
11 - [Friendica-specific](help/API-Friendica)
12 - [GNU Social](help/API-GNU-Social)
13
14 ## Usage
15
16 ### HTTP Method
17
18 API endpoints can restrict the HTTP method used to request them.
19 Using an invalid method results in HTTP error 405 "Method Not Allowed".
20
21 ### Authentication
22
23 Friendica supports basic HTTP Auth and OAuth to authenticate the user to the APIs.
24
25 ### Errors
26
27 When an error occurs in API call, an HTTP error code is returned, with an error message
28 Usually:
29
30 * 400 Bad Request: if parameters are missing or items can't be found
31 * 403 Forbidden: if the authenticated user is missing
32 * 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
33 * 501 Not Implemented: if the requested API doesn't exist
34 * 500 Internal Server Error: on other error conditions
35
36 Error body is
37
38 json:
39
40 ```json
41 {
42     "error": "Specific error message",
43     "request": "API path requested",
44     "code": "HTTP error code"
45 }
46 ```
47
48 xml:
49
50 ```xml
51 <status>
52     <error>Specific error message</error>
53     <request>API path requested</request>
54     <code>HTTP error code</code>
55 </status>
56 ```
57
58 ## Usage Examples
59
60 ### BASH / cURL
61
62 ```bash
63 /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"
64 ```
65
66 ### Python
67
68 The [RSStoFriendika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
69 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
70
71 def tweet(server, message, group_allow=None):
72 url = server + '/api/statuses/update'
73 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
74
75 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.