]> git.mxchange.org Git - friendica.git/blob - doc/api.md
Merge pull request #8977 from annando/fix-contact-search
[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 1 to authenticate the user to the APIs.
24
25 OAuth settings can be added by the user in web UI under [/settings/oauth/](/settings/oauth/).
26
27 ### Errors
28
29 When an error occurs in API call, an HTTP error code is returned, with an error message
30 Usually:
31
32 * 400 Bad Request: if parameters are missing or items can't be found
33 * 403 Forbidden: if the authenticated user is missing
34 * 405 Method Not Allowed: if API was called with an invalid method, eg. GET when API require POST
35 * 501 Not Implemented: if the requested API doesn't exist
36 * 500 Internal Server Error: on other error conditions
37
38 Error body is
39
40 json:
41
42 ```json
43 {
44     "error": "Specific error message",
45     "request": "API path requested",
46     "code": "HTTP error code"
47 }
48 ```
49
50 xml:
51
52 ```xml
53 <status>
54     <error>Specific error message</error>
55     <request>API path requested</request>
56     <code>HTTP error code</code>
57 </status>
58 ```
59
60 ## Usage Examples
61
62 ### BASH / cURL
63
64 ```bash
65 /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"
66 ```
67
68 ### Python
69
70 The [RSStoFriendika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
71 The lines for posting are located at [line 21](https://github.com/pafcu/RSStoFriendika/blob/master/RSStoFriendika.py#L21) and following.
72
73 def tweet(server, message, group_allow=None):
74 url = server + '/api/statuses/update'
75 urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
76
77 There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.