friendica-github/doc/api.md

78 lines
2.1 KiB
Markdown
Raw Normal View History

# Using the APIs
2017-12-19 11:07:31 +00:00
<!-- markdownlint-disable MD010 MD013 MD024 -->
* [Home](help)
Friendica offers multiple API endpoints to interface with third-party applications:
- [Twitter](help/API-Twitter)
- [Mastodon](help/API-Mastodon)
- [Friendica-specific](help/API-Friendica)
- [GNU Social](help/API-GNU-Social)
## Usage
### HTTP Method
2017-12-19 11:07:31 +00:00
API endpoints can restrict the HTTP method used to request them.
Using an invalid method results in HTTP error 405 "Method Not Allowed".
### Authentication
2017-12-19 11:07:31 +00:00
Friendica supports basic HTTP Auth and OAuth 1 to authenticate the user to the APIs.
OAuth settings can be added by the user in web UI under [/settings/oauth/](/settings/oauth/).
2017-12-19 11:07:31 +00:00
### Errors
2017-12-19 11:07:31 +00:00
2017-05-19 20:37:45 +00:00
When an error occurs in API call, an HTTP error code is returned, with an error message
Usually:
2017-12-19 11:07:31 +00:00
* 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:
2017-12-19 11:07:31 +00:00
```json
2019-07-30 05:36:06 +00:00
{
"error": "Specific error message",
"request": "API path requested",
"code": "HTTP error code"
2019-07-30 05:36:06 +00:00
}
```
2017-12-19 11:07:31 +00:00
xml:
```xml
<status>
<error>Specific error message</error>
<request>API path requested</request>
<code>HTTP error code</code>
</status>
```
## Usage Examples
2017-12-19 11:07:31 +00:00
### BASH / cURL
2017-12-19 11:07:31 +00:00
```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"
2017-12-19 11:07:31 +00:00
```
### Python
2017-12-19 11:07:31 +00:00
The [RSStoFriendika](https://github.com/pafcu/RSStoFriendika) code can be used as an example of how to use the API with python.
2017-09-24 10:05:28 +00:00
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):
url = server + '/api/statuses/update'
urllib2.urlopen(url, urllib.urlencode({'status': message,'group_allow[]':group_allow}, doseq=True))
There is also a [module for python 3](https://bitbucket.org/tobiasd/python-friendica) for using the API.