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.