<commit_before>Friendica API
===
The Friendica API aims to be compatible to the [GNU Social API](http://wiki.gnusocial.de/gnusocial:api) and the [Twitter API](https://dev.twitter.com/rest/public).

Please refer to the linked documentation for further information.

## Implemented API calls

### General
#### HTTP Method

API endpoints can restrict the method used to request them.
Using an invalid method results in HTTP error 405 "Method Not Allowed".

In this document, the required method is listed after the endpoint name. "*" means every method can be used.

#### Auth

Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.

OAuth settings can be added by the user in web UI under /settings/oauth/

In this document, endpoints which requires auth are marked with "AUTH" after endpoint name

#### Unsupported parameters
* cursor: Not implemented in GNU Social
* trim_user: Not implemented in GNU Social
* contributor_details: Not implemented in GNU Social
* place_id: Not implemented in GNU Social
* display_coordinates: Not implemented in GNU Social
* include_rts: To-Do
* include_my_retweet: Retweets in Friendica are implemented in a different way

#### Different behaviour
* screen_name: The nick name in friendica is only unique in each network but not for all networks. The users are searched in the following priority: Friendica, StatusNet/GNU Social, Diaspora, pump.io, Twitter. If no contact was found by this way, then the first contact is taken.
* include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.

#### Return values
* 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 (*; AUTH)

---
### account/verify_credentials (*; AUTH)
#### Parameters

* skip_status: Don't show the "status" field. (Default: false)
* include_entities: "true" shows entities for pictures and links (Default: false)

---
### conversation/show (*; AUTH)
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.

#### Parameter
* id: id of the post
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false)

#### Unsupported parameters
* include_rts
* trim_user
* contributor_details

---
### direct_messages (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false)
* friendica_verbose: "true" enables different error returns for Windows 10 app (default: "false")

#### Unsupported parameters
* skip_status

---
### direct_messages/all (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* friendica_verbose: "true" enables different error returns for Windows 10 app (default: "false")

---
### direct_messages/conversation (*; AUTH)
Shows all direct messages of a conversation
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* uri: URI of the conversation
* friendica_verbose: "true" enables different error returns for Windows 10 app (default: "false")

---
### direct_messages/sent (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false)
* friendica_verbose: "true" enables different error returns for Windows 10 app (default: "false")

---
### direct_messages/new (POST,PUT; AUTH)
#### Parameters
* user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!)
* text: The message
* replyto: ID of the replied direct message
* title: Title of the direct message

---
### direct_messages/destroy (POST,DELETE; AUTH)
#### Parameters
* id: id of the message to be deleted
* include_entities: optional, currently not yet implemented
* friendica_parenturi: optional, can be used for increased safety to delete only intended messages
* friendica_verbose: "true" enables different error returns for Windows 10 app (default: "false")

#### Return values

On success:
* JSON return as defined for Twitter API not yet implemented
* on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}

On error:<commit_msg>adapted documentation<commit_after>Friendica API
===
The Friendica API aims to be compatible to the [GNU Social API](http://wiki.gnusocial.de/gnusocial:api) and the [Twitter API](https://dev.twitter.com/rest/public).

Please refer to the linked documentation for further information.

## Implemented API calls

### General
#### HTTP Method

API endpoints can restrict the method used to request them.
Using an invalid method results in HTTP error 405 "Method Not Allowed".

In this document, the required method is listed after the endpoint name. "*" means every method can be used.

#### Auth

Friendica supports basic http auth and OAuth 1 to authenticate the user to the api.

OAuth settings can be added by the user in web UI under /settings/oauth/

In this document, endpoints which requires auth are marked with "AUTH" after endpoint name

#### Unsupported parameters
* cursor: Not implemented in GNU Social
* trim_user: Not implemented in GNU Social
* contributor_details: Not implemented in GNU Social
* place_id: Not implemented in GNU Social
* display_coordinates: Not implemented in GNU Social
* include_rts: To-Do
* include_my_retweet: Retweets in Friendica are implemented in a different way

#### Different behaviour
* screen_name: The nick name in friendica is only unique in each network but not for all networks. The users are searched in the following priority: Friendica, StatusNet/GNU Social, Diaspora, pump.io, Twitter. If no contact was found by this way, then the first contact is taken.
* include_entities: Default is "false". If set to "true" then the plain text is formatted so that links are having descriptions.

#### Return values
* 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 (*; AUTH)

---
### account/verify_credentials (*; AUTH)
#### Parameters

* skip_status: Don't show the "status" field. (Default: false)
* include_entities: "true" shows entities for pictures and links (Default: false)

---
### conversation/show (*; AUTH)
Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id.

#### Parameter
* id: id of the post
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* include_entities: "true" shows entities for pictures and links (Default: false)

#### Unsupported parameters
* include_rts
* trim_user
* contributor_details

---
### direct_messages (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false)
* friendica_verbose: "true" enables different error returns (default: "false")

#### Unsupported parameters
* skip_status

---
### direct_messages/all (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* friendica_verbose: "true" enables different error returns (default: "false")

---
### direct_messages/conversation (*; AUTH)
Shows all direct messages of a conversation
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* uri: URI of the conversation
* friendica_verbose: "true" enables different error returns (default: "false")

---
### direct_messages/sent (*; AUTH)
#### Parameters
* count: Items per page (default: 20)
* page: page number
* since_id: minimal id
* max_id: maximum id
* getText: Defines the format of the status field. Can be "html" or "plain"
* include_entities: "true" shows entities for pictures and links (Default: false)
* friendica_verbose: "true" enables different error returns (default: "false")

---
### direct_messages/new (POST,PUT; AUTH)
#### Parameters
* user_id: id of the user
* screen_name: screen name (for technical reasons, this value is not unique!)
* text: The message
* replyto: ID of the replied direct message
* title: Title of the direct message

---
### direct_messages/destroy (POST,DELETE; AUTH)
#### Parameters
* id: id of the message to be deleted
* include_entities: optional, currently not yet implemented
* friendica_parenturi: optional, can be used for increased safety to delete only intended messages
* friendica_verbose: "true" enables different error returns (default: "false")

#### Return values

On success:
* JSON return as defined for Twitter API not yet implemented
* on friendica_verbose=true: JSON return {"result":"ok","message":"message deleted"}

On error:
{'fraction_non_alphanumeric': 0.09934311167101592, 'fraction_numerical': 0.006118959776837938, 'mean_word_length': 4.752587991718427, 'pattern_counts': {'":': 10, '<': 19, '<?xml version=': 0, '>': 19, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7263057', 'n_tokens_mistral': 3150, 'n_tokens_neox': 3030, 'n_words': 1438}