From 17838366a06d05e6b9b7849437fceeebf8e62d79 Mon Sep 17 00:00:00 2001 From: Hypolite Petovan Date: Tue, 3 Dec 2019 23:24:32 -0500 Subject: [PATCH 1/7] Reformat library/OAuth1 - Add type hints to Network\FKOAuthDataStore --- library/OAuth1.php | 1605 ++++++++++++++++-------------- src/Network/FKOAuthDataStore.php | 50 +- 2 files changed, 873 insertions(+), 782 deletions(-) diff --git a/library/OAuth1.php b/library/OAuth1.php index e3ca24646..041b0e690 100644 --- a/library/OAuth1.php +++ b/library/OAuth1.php @@ -3,65 +3,73 @@ /* Generic exception class */ + +use Friendica\Network\FKOAuthDataStore; + if (!class_exists('OAuthException', false)) { - class OAuthException extends Exception - { } + class OAuthException extends Exception + { + } } class OAuthConsumer { - public $key; - public $secret; + public $key; + public $secret; + public $callback_url; - function __construct($key, $secret, $callback_url = NULL) - { - $this->key = $key; - $this->secret = $secret; - $this->callback_url = $callback_url; - } + function __construct($key, $secret, $callback_url = NULL) + { + $this->key = $key; + $this->secret = $secret; + $this->callback_url = $callback_url; + } - function __toString() - { - return "OAuthConsumer[key=$this->key,secret=$this->secret]"; - } + function __toString() + { + return "OAuthConsumer[key=$this->key,secret=$this->secret]"; + } } class OAuthToken { - // access tokens and request tokens - public $key; - public $secret; + // access tokens and request tokens + public $key; + public $secret; - public $expires; - public $scope; - public $uid; + public $expires; + public $scope; + public $uid; - /** - * key = the token - * secret = the token secret - */ - function __construct($key, $secret) - { - $this->key = $key; - $this->secret = $secret; - } + /** + * key = the token + * secret = the token secret + * + * @param $key + * @param $secret + */ + function __construct($key, $secret) + { + $this->key = $key; + $this->secret = $secret; + } - /** - * generates the basic string serialization of a token that a server - * would respond to request_token and access_token calls with - */ - function to_string() - { - return "oauth_token=" . - OAuthUtil::urlencode_rfc3986($this->key) . - "&oauth_token_secret=" . - OAuthUtil::urlencode_rfc3986($this->secret); - } + /** + * generates the basic string serialization of a token that a server + * would respond to request_token and access_token calls with + */ + function to_string() + { + return "oauth_token=" . + OAuthUtil::urlencode_rfc3986($this->key) . + "&oauth_token_secret=" . + OAuthUtil::urlencode_rfc3986($this->secret); + } - function __toString() - { - return $this->to_string(); - } + function __toString() + { + return $this->to_string(); + } } /** @@ -70,37 +78,40 @@ class OAuthToken */ abstract class OAuthSignatureMethod { - /** - * Needs to return the name of the Signature Method (ie HMAC-SHA1) - * @return string - */ - abstract public function get_name(); + /** + * Needs to return the name of the Signature Method (ie HMAC-SHA1) + * + * @return string + */ + abstract public function get_name(); - /** - * Build up the signature - * NOTE: The output of this function MUST NOT be urlencoded. - * the encoding is handled in OAuthRequest when the final - * request is serialized - * @param OAuthRequest $request - * @param OAuthConsumer $consumer - * @param OAuthToken $token - * @return string - */ - abstract public function build_signature($request, $consumer, $token); + /** + * Build up the signature + * NOTE: The output of this function MUST NOT be urlencoded. + * the encoding is handled in OAuthRequest when the final + * request is serialized + * + * @param OAuthRequest $request + * @param OAuthConsumer $consumer + * @param OAuthToken $token + * @return string + */ + abstract public function build_signature(OAuthRequest $request, OAuthConsumer $consumer, OAuthToken $token); - /** - * Verifies that a given signature is correct - * @param OAuthRequest $request - * @param OAuthConsumer $consumer - * @param OAuthToken $token - * @param string $signature - * @return bool - */ - public function check_signature($request, $consumer, $token, $signature) - { - $built = $this->build_signature($request, $consumer, $token); - return ($built == $signature); - } + /** + * Verifies that a given signature is correct + * + * @param OAuthRequest $request + * @param OAuthConsumer $consumer + * @param OAuthToken $token + * @param string $signature + * @return bool + */ + public function check_signature($request, $consumer, $token, $signature) + { + $built = $this->build_signature($request, $consumer, $token); + return ($built == $signature); + } } /** @@ -112,28 +123,34 @@ abstract class OAuthSignatureMethod */ class OAuthSignatureMethod_HMAC_SHA1 extends OAuthSignatureMethod { - function get_name() - { - return "HMAC-SHA1"; - } + function get_name() + { + return "HMAC-SHA1"; + } - public function build_signature($request, $consumer, $token) - { - $base_string = $request->get_signature_base_string(); - $request->base_string = $base_string; + /** + * @param OAuthRequest $request + * @param OAuthConsumer $consumer + * @param OAuthToken $token + * @return string + */ + public function build_signature(OAuthRequest $request, OAuthConsumer $consumer, OAuthToken $token) + { + $base_string = $request->get_signature_base_string(); + $request->base_string = $base_string; - $key_parts = array( - $consumer->secret, - ($token) ? $token->secret : "" - ); + $key_parts = array( + $consumer->secret, + ($token) ? $token->secret : "" + ); - $key_parts = OAuthUtil::urlencode_rfc3986($key_parts); - $key = implode('&', $key_parts); + $key_parts = OAuthUtil::urlencode_rfc3986($key_parts); + $key = implode('&', $key_parts); - $r = base64_encode(hash_hmac('sha1', $base_string, $key, true)); - return $r; - } + $r = base64_encode(hash_hmac('sha1', $base_string, $key, true)); + return $r; + } } /** @@ -143,33 +160,38 @@ class OAuthSignatureMethod_HMAC_SHA1 extends OAuthSignatureMethod */ class OAuthSignatureMethod_PLAINTEXT extends OAuthSignatureMethod { - public function get_name() - { - return "PLAINTEXT"; - } + public function get_name() + { + return "PLAINTEXT"; + } - /** - * oauth_signature is set to the concatenated encoded values of the Consumer Secret and - * Token Secret, separated by a '&' character (ASCII code 38), even if either secret is - * empty. The result MUST be encoded again. - * - Chapter 9.4.1 ("Generating Signatures") - * - * Please note that the second encoding MUST NOT happen in the SignatureMethod, as - * OAuthRequest handles this! - */ - public function build_signature($request, $consumer, $token) - { - $key_parts = array( - $consumer->secret, - ($token) ? $token->secret : "" - ); + /** + * oauth_signature is set to the concatenated encoded values of the Consumer Secret and + * Token Secret, separated by a '&' character (ASCII code 38), even if either secret is + * empty. The result MUST be encoded again. + * - Chapter 9.4.1 ("Generating Signatures") + * + * Please note that the second encoding MUST NOT happen in the SignatureMethod, as + * OAuthRequest handles this! + * + * @param $request + * @param $consumer + * @param $token + * @return string + */ + public function build_signature(OAuthRequest $request, OAuthConsumer $consumer, OAuthToken $token) + { + $key_parts = array( + $consumer->secret, + ($token) ? $token->secret : "" + ); - $key_parts = OAuthUtil::urlencode_rfc3986($key_parts); - $key = implode('&', $key_parts); - $request->base_string = $key; + $key_parts = OAuthUtil::urlencode_rfc3986($key_parts); + $key = implode('&', $key_parts); + $request->base_string = $key; - return $key; - } + return $key; + } } /** @@ -182,774 +204,841 @@ class OAuthSignatureMethod_PLAINTEXT extends OAuthSignatureMethod */ abstract class OAuthSignatureMethod_RSA_SHA1 extends OAuthSignatureMethod { - public function get_name() - { - return "RSA-SHA1"; - } + public function get_name() + { + return "RSA-SHA1"; + } - // Up to the SP to implement this lookup of keys. Possible ideas are: - // (1) do a lookup in a table of trusted certs keyed off of consumer - // (2) fetch via http using a url provided by the requester - // (3) some sort of specific discovery code based on request - // - // Either way should return a string representation of the certificate - protected abstract function fetch_public_cert(&$request); + // Up to the SP to implement this lookup of keys. Possible ideas are: + // (1) do a lookup in a table of trusted certs keyed off of consumer + // (2) fetch via http using a url provided by the requester + // (3) some sort of specific discovery code based on request + // + // Either way should return a string representation of the certificate + protected abstract function fetch_public_cert(&$request); - // Up to the SP to implement this lookup of keys. Possible ideas are: - // (1) do a lookup in a table of trusted certs keyed off of consumer - // - // Either way should return a string representation of the certificate - protected abstract function fetch_private_cert(&$request); + // Up to the SP to implement this lookup of keys. Possible ideas are: + // (1) do a lookup in a table of trusted certs keyed off of consumer + // + // Either way should return a string representation of the certificate + protected abstract function fetch_private_cert(&$request); - public function build_signature($request, $consumer, $token) - { - $base_string = $request->get_signature_base_string(); - $request->base_string = $base_string; + public function build_signature(OAuthRequest $request, OAuthConsumer $consumer, OAuthToken $token) + { + $base_string = $request->get_signature_base_string(); + $request->base_string = $base_string; - // Fetch the private key cert based on the request - $cert = $this->fetch_private_cert($request); + // Fetch the private key cert based on the request + $cert = $this->fetch_private_cert($request); - // Pull the private key ID from the certificate - $privatekeyid = openssl_get_privatekey($cert); + // Pull the private key ID from the certificate + $privatekeyid = openssl_get_privatekey($cert); - // Sign using the key - $ok = openssl_sign($base_string, $signature, $privatekeyid); + // Sign using the key + openssl_sign($base_string, $signature, $privatekeyid); - // Release the key resource - openssl_free_key($privatekeyid); + // Release the key resource + openssl_free_key($privatekeyid); - return base64_encode($signature); - } + return base64_encode($signature); + } - public function check_signature($request, $consumer, $token, $signature) - { - $decoded_sig = base64_decode($signature); + public function check_signature($request, $consumer, $token, $signature) + { + $decoded_sig = base64_decode($signature); - $base_string = $request->get_signature_base_string(); + $base_string = $request->get_signature_base_string(); - // Fetch the public key cert based on the request - $cert = $this->fetch_public_cert($request); + // Fetch the public key cert based on the request + $cert = $this->fetch_public_cert($request); - // Pull the public key ID from the certificate - $publickeyid = openssl_get_publickey($cert); + // Pull the public key ID from the certificate + $publickeyid = openssl_get_publickey($cert); - // Check the computed signature against the one passed in the query - $ok = openssl_verify($base_string, $decoded_sig, $publickeyid); + // Check the computed signature against the one passed in the query + $ok = openssl_verify($base_string, $decoded_sig, $publickeyid); - // Release the key resource - openssl_free_key($publickeyid); + // Release the key resource + openssl_free_key($publickeyid); - return $ok == 1; - } + return $ok == 1; + } } class OAuthRequest { - private $parameters; - private $http_method; - private $http_url; - // for debug purposes - public $base_string; - public static $version = '1.0'; - public static $POST_INPUT = 'php://input'; + private $parameters; + private $http_method; + private $http_url; + // for debug purposes + public $base_string; + public static $version = '1.0'; + public static $POST_INPUT = 'php://input'; - function __construct($http_method, $http_url, $parameters = NULL) - { - @$parameters or $parameters = array(); - $parameters = array_merge(OAuthUtil::parse_parameters(parse_url($http_url, PHP_URL_QUERY)), $parameters); - $this->parameters = $parameters; - $this->http_method = $http_method; - $this->http_url = $http_url; - } + function __construct($http_method, $http_url, $parameters = NULL) + { + @$parameters or $parameters = array(); + $parameters = array_merge(OAuthUtil::parse_parameters(parse_url($http_url, PHP_URL_QUERY)), $parameters); + $this->parameters = $parameters; + $this->http_method = $http_method; + $this->http_url = $http_url; + } - /** - * attempt to build up a request from what was passed to the server - */ - public static function from_request($http_method = NULL, $http_url = NULL, $parameters = NULL) - { - $scheme = (!isset($_SERVER['HTTPS']) || $_SERVER['HTTPS'] != "on") - ? 'http' - : 'https'; - @$http_url or $http_url = $scheme . - '://' . $_SERVER['HTTP_HOST'] . - ':' . - $_SERVER['SERVER_PORT'] . - $_SERVER['REQUEST_URI']; - @$http_method or $http_method = $_SERVER['REQUEST_METHOD']; + /** + * attempt to build up a request from what was passed to the server + * + * @param string|null $http_method + * @param string|null $http_url + * @param string|null $parameters + * @return OAuthRequest + */ + public static function from_request($http_method = NULL, $http_url = NULL, $parameters = NULL) + { + $scheme = (!isset($_SERVER['HTTPS']) || $_SERVER['HTTPS'] != "on") + ? 'http' + : 'https'; + @$http_url or $http_url = $scheme . + '://' . $_SERVER['HTTP_HOST'] . + ':' . + $_SERVER['SERVER_PORT'] . + $_SERVER['REQUEST_URI']; + @$http_method or $http_method = $_SERVER['REQUEST_METHOD']; - // We weren't handed any parameters, so let's find the ones relevant to - // this request. - // If you run XML-RPC or similar you should use this to provide your own - // parsed parameter-list - if (!$parameters) { - // Find request headers - $request_headers = OAuthUtil::get_headers(); + // We weren't handed any parameters, so let's find the ones relevant to + // this request. + // If you run XML-RPC or similar you should use this to provide your own + // parsed parameter-list + if (!$parameters) { + // Find request headers + $request_headers = OAuthUtil::get_headers(); - // Parse the query-string to find GET parameters - $parameters = OAuthUtil::parse_parameters($_SERVER['QUERY_STRING']); + // Parse the query-string to find GET parameters + $parameters = OAuthUtil::parse_parameters($_SERVER['QUERY_STRING']); - // It's a POST request of the proper content-type, so parse POST - // parameters and add those overriding any duplicates from GET - if ( - $http_method == "POST" - && @strstr( - $request_headers["Content-Type"], - "application/x-www-form-urlencoded" - ) - ) { - $post_data = OAuthUtil::parse_parameters( - file_get_contents(self::$POST_INPUT) - ); - $parameters = array_merge($parameters, $post_data); - } + // It's a POST request of the proper content-type, so parse POST + // parameters and add those overriding any duplicates from GET + if ( + $http_method == "POST" + && @strstr( + $request_headers["Content-Type"], + "application/x-www-form-urlencoded" + ) + ) { + $post_data = OAuthUtil::parse_parameters( + file_get_contents(self::$POST_INPUT) + ); + $parameters = array_merge($parameters, $post_data); + } - // We have a Authorization-header with OAuth data. Parse the header - // and add those overriding any duplicates from GET or POST - if (@substr($request_headers['Authorization'], 0, 6) == "OAuth ") { - $header_parameters = OAuthUtil::split_header( - $request_headers['Authorization'] - ); - $parameters = array_merge($parameters, $header_parameters); - } - } - // fix for friendica redirect system + // We have a Authorization-header with OAuth data. Parse the header + // and add those overriding any duplicates from GET or POST + if (@substr($request_headers['Authorization'], 0, 6) == "OAuth ") { + $header_parameters = OAuthUtil::split_header( + $request_headers['Authorization'] + ); + $parameters = array_merge($parameters, $header_parameters); + } + } + // fix for friendica redirect system - $http_url = substr($http_url, 0, strpos($http_url, $parameters['pagename']) + strlen($parameters['pagename'])); - unset($parameters['pagename']); + $http_url = substr($http_url, 0, strpos($http_url, $parameters['pagename']) + strlen($parameters['pagename'])); + unset($parameters['pagename']); - return new OAuthRequest($http_method, $http_url, $parameters); - } + return new OAuthRequest($http_method, $http_url, $parameters); + } - /** - * pretty much a helper function to set up the request - */ - public static function from_consumer_and_token($consumer, $token, $http_method, $http_url, $parameters = NULL) - { - @$parameters or $parameters = array(); - $defaults = array( - "oauth_version" => OAuthRequest::$version, - "oauth_nonce" => OAuthRequest::generate_nonce(), - "oauth_timestamp" => OAuthRequest::generate_timestamp(), - "oauth_consumer_key" => $consumer->key - ); - if ($token) - $defaults['oauth_token'] = $token->key; + /** + * pretty much a helper function to set up the request + * + * @param OAuthConsumer $consumer + * @param OAuthToken $token + * @param string $http_method + * @param string $http_url + * @param array|null $parameters + * @return OAuthRequest + */ + public static function from_consumer_and_token(OAuthConsumer $consumer, OAuthToken $token, $http_method, $http_url, array $parameters = NULL) + { + @$parameters or $parameters = array(); + $defaults = array( + "oauth_version" => OAuthRequest::$version, + "oauth_nonce" => OAuthRequest::generate_nonce(), + "oauth_timestamp" => OAuthRequest::generate_timestamp(), + "oauth_consumer_key" => $consumer->key + ); + if ($token) + $defaults['oauth_token'] = $token->key; - $parameters = array_merge($defaults, $parameters); + $parameters = array_merge($defaults, $parameters); - return new OAuthRequest($http_method, $http_url, $parameters); - } + return new OAuthRequest($http_method, $http_url, $parameters); + } - public function set_parameter($name, $value, $allow_duplicates = true) - { - if ($allow_duplicates && isset($this->parameters[$name])) { - // We have already added parameter(s) with this name, so add to the list - if (is_scalar($this->parameters[$name])) { - // This is the first duplicate, so transform scalar (string) - // into an array so we can add the duplicates - $this->parameters[$name] = array($this->parameters[$name]); - } + public function set_parameter($name, $value, $allow_duplicates = true) + { + if ($allow_duplicates && isset($this->parameters[$name])) { + // We have already added parameter(s) with this name, so add to the list + if (is_scalar($this->parameters[$name])) { + // This is the first duplicate, so transform scalar (string) + // into an array so we can add the duplicates + $this->parameters[$name] = array($this->parameters[$name]); + } - $this->parameters[$name][] = $value; - } else { - $this->parameters[$name] = $value; - } - } + $this->parameters[$name][] = $value; + } else { + $this->parameters[$name] = $value; + } + } - public function get_parameter($name) - { - return isset($this->parameters[$name]) ? $this->parameters[$name] : null; - } + public function get_parameter($name) + { + return isset($this->parameters[$name]) ? $this->parameters[$name] : null; + } - public function get_parameters() - { - return $this->parameters; - } + public function get_parameters() + { + return $this->parameters; + } - public function unset_parameter($name) - { - unset($this->parameters[$name]); - } + public function unset_parameter($name) + { + unset($this->parameters[$name]); + } - /** - * The request parameters, sorted and concatenated into a normalized string. - * @return string - */ - public function get_signable_parameters() - { - // Grab all parameters - $params = $this->parameters; + /** + * The request parameters, sorted and concatenated into a normalized string. + * + * @return string + */ + public function get_signable_parameters() + { + // Grab all parameters + $params = $this->parameters; - // Remove oauth_signature if present - // Ref: Spec: 9.1.1 ("The oauth_signature parameter MUST be excluded.") - if (isset($params['oauth_signature'])) { - unset($params['oauth_signature']); - } + // Remove oauth_signature if present + // Ref: Spec: 9.1.1 ("The oauth_signature parameter MUST be excluded.") + if (isset($params['oauth_signature'])) { + unset($params['oauth_signature']); + } - return OAuthUtil::build_http_query($params); - } + return OAuthUtil::build_http_query($params); + } - /** - * Returns the base string of this request - * - * The base string defined as the method, the url - * and the parameters (normalized), each urlencoded - * and the concated with &. - */ - public function get_signature_base_string() - { - $parts = array( - $this->get_normalized_http_method(), - $this->get_normalized_http_url(), - $this->get_signable_parameters() - ); + /** + * Returns the base string of this request + * + * The base string defined as the method, the url + * and the parameters (normalized), each urlencoded + * and the concated with &. + */ + public function get_signature_base_string() + { + $parts = array( + $this->get_normalized_http_method(), + $this->get_normalized_http_url(), + $this->get_signable_parameters() + ); - $parts = OAuthUtil::urlencode_rfc3986($parts); + $parts = OAuthUtil::urlencode_rfc3986($parts); - return implode('&', $parts); - } + return implode('&', $parts); + } - /** - * just uppercases the http method - */ - public function get_normalized_http_method() - { - return strtoupper($this->http_method); - } + /** + * just uppercases the http method + */ + public function get_normalized_http_method() + { + return strtoupper($this->http_method); + } - /** - * parses the url and rebuilds it to be - * scheme://host/path - */ - public function get_normalized_http_url() - { - $parts = parse_url($this->http_url); + /** + * parses the url and rebuilds it to be + * scheme://host/path + */ + public function get_normalized_http_url() + { + $parts = parse_url($this->http_url); - $port = @$parts['port']; - $scheme = $parts['scheme']; - $host = $parts['host']; - $path = @$parts['path']; + $port = @$parts['port']; + $scheme = $parts['scheme']; + $host = $parts['host']; + $path = @$parts['path']; - $port or $port = ($scheme == 'https') ? '443' : '80'; + $port or $port = ($scheme == 'https') ? '443' : '80'; - if (($scheme == 'https' && $port != '443') - || ($scheme == 'http' && $port != '80') - ) { - $host = "$host:$port"; - } - return "$scheme://$host$path"; - } + if (($scheme == 'https' && $port != '443') + || ($scheme == 'http' && $port != '80') + ) { + $host = "$host:$port"; + } + return "$scheme://$host$path"; + } - /** - * builds a url usable for a GET request - */ - public function to_url() - { - $post_data = $this->to_postdata(); - $out = $this->get_normalized_http_url(); - if ($post_data) { - $out .= '?' . $post_data; - } - return $out; - } + /** + * builds a url usable for a GET request + */ + public function to_url() + { + $post_data = $this->to_postdata(); + $out = $this->get_normalized_http_url(); + if ($post_data) { + $out .= '?' . $post_data; + } + return $out; + } - /** - * builds the data one would send in a POST request - */ - public function to_postdata($raw = false) - { - if ($raw) - return $this->parameters; - else - return OAuthUtil::build_http_query($this->parameters); - } + /** + * builds the data one would send in a POST request + * + * @param bool $raw + * @return array|string + */ + public function to_postdata(bool $raw = false) + { + if ($raw) + return $this->parameters; + else + return OAuthUtil::build_http_query($this->parameters); + } - /** - * builds the Authorization: header - */ - public function to_header($realm = null) - { - $first = true; - if ($realm) { - $out = 'Authorization: OAuth realm="' . OAuthUtil::urlencode_rfc3986($realm) . '"'; - $first = false; - } else - $out = 'Authorization: OAuth'; + /** + * builds the Authorization: header + * + * @param string|null $realm + * @return string + * @throws OAuthException + */ + public function to_header($realm = null) + { + $first = true; + if ($realm) { + $out = 'Authorization: OAuth realm="' . OAuthUtil::urlencode_rfc3986($realm) . '"'; + $first = false; + } else + $out = 'Authorization: OAuth'; - foreach ($this->parameters as $k => $v) { - if (substr($k, 0, 5) != "oauth") continue; - if (is_array($v)) { - throw new OAuthException('Arrays not supported in headers'); - } - $out .= ($first) ? ' ' : ','; - $out .= OAuthUtil::urlencode_rfc3986($k) . - '="' . - OAuthUtil::urlencode_rfc3986($v) . - '"'; - $first = false; - } - return $out; - } + foreach ($this->parameters as $k => $v) { + if (substr($k, 0, 5) != "oauth") continue; + if (is_array($v)) { + throw new OAuthException('Arrays not supported in headers'); + } + $out .= ($first) ? ' ' : ','; + $out .= OAuthUtil::urlencode_rfc3986($k) . + '="' . + OAuthUtil::urlencode_rfc3986($v) . + '"'; + $first = false; + } + return $out; + } - public function __toString() - { - return $this->to_url(); - } + public function __toString() + { + return $this->to_url(); + } - public function sign_request($signature_method, $consumer, $token) - { - $this->set_parameter( - "oauth_signature_method", - $signature_method->get_name(), - false - ); - $signature = $this->build_signature($signature_method, $consumer, $token); - $this->set_parameter("oauth_signature", $signature, false); - } + public function sign_request(OAuthSignatureMethod $signature_method, $consumer, $token) + { + $this->set_parameter( + "oauth_signature_method", + $signature_method->get_name(), + false + ); + $signature = $this->build_signature($signature_method, $consumer, $token); + $this->set_parameter("oauth_signature", $signature, false); + } - public function build_signature($signature_method, $consumer, $token) - { - $signature = $signature_method->build_signature($this, $consumer, $token); - return $signature; - } + public function build_signature(OAuthSignatureMethod $signature_method, $consumer, $token) + { + $signature = $signature_method->build_signature($this, $consumer, $token); + return $signature; + } - /** - * util function: current timestamp - */ - private static function generate_timestamp() - { - return time(); - } + /** + * util function: current timestamp + */ + private static function generate_timestamp() + { + return time(); + } - /** - * util function: current nonce - */ - private static function generate_nonce() - { - return Friendica\Util\Strings::getRandomHex(32); - } + /** + * util function: current nonce + */ + private static function generate_nonce() + { + return Friendica\Util\Strings::getRandomHex(32); + } } class OAuthServer { - protected $timestamp_threshold = 300; // in seconds, five minutes - protected $version = '1.0'; // hi blaine - protected $signature_methods = array(); + protected $timestamp_threshold = 300; // in seconds, five minutes + protected $version = '1.0'; // hi blaine + /** @var OAuthSignatureMethod[] */ + protected $signature_methods = array(); - protected $data_store; + /** @var FKOAuthDataStore */ + protected $data_store; - function __construct($data_store) - { - $this->data_store = $data_store; - } + function __construct(FKOAuthDataStore $data_store) + { + $this->data_store = $data_store; + } - public function add_signature_method($signature_method) - { - $this->signature_methods[$signature_method->get_name()] = - $signature_method; - } + public function add_signature_method(OAuthSignatureMethod $signature_method) + { + $this->signature_methods[$signature_method->get_name()] = + $signature_method; + } - // high level functions + // high level functions - /** - * process a request_token request - * returns the request token on success - */ - public function fetch_request_token(&$request) - { - $this->get_version($request); + /** + * process a request_token request + * returns the request token on success + * + * @param OAuthRequest $request + * @return OAuthToken|null + * @throws OAuthException + */ + public function fetch_request_token(OAuthRequest $request) + { + $this->get_version($request); - $consumer = $this->get_consumer($request); + $consumer = $this->get_consumer($request); - // no token required for the initial token request - $token = NULL; + // no token required for the initial token request + $token = NULL; - $this->check_signature($request, $consumer, $token); + $this->check_signature($request, $consumer, $token); - // Rev A change - $callback = $request->get_parameter('oauth_callback'); - $new_token = $this->data_store->new_request_token($consumer, $callback); + // Rev A change + $callback = $request->get_parameter('oauth_callback'); + $new_token = $this->data_store->new_request_token($consumer, $callback); - return $new_token; - } + return $new_token; + } - /** - * process an access_token request - * returns the access token on success - */ - public function fetch_access_token(&$request) - { - $this->get_version($request); + /** + * process an access_token request + * returns the access token on success + * + * @param OAuthRequest $request + * @return object + * @throws OAuthException + */ + public function fetch_access_token(OAuthRequest $request) + { + $this->get_version($request); - $consumer = $this->get_consumer($request); + $consumer = $this->get_consumer($request); - // requires authorized request token - $token = $this->get_token($request, $consumer, "request"); + // requires authorized request token + $token = $this->get_token($request, $consumer, "request"); - $this->check_signature($request, $consumer, $token); + $this->check_signature($request, $consumer, $token); - // Rev A change - $verifier = $request->get_parameter('oauth_verifier'); - $new_token = $this->data_store->new_access_token($token, $consumer, $verifier); + // Rev A change + $verifier = $request->get_parameter('oauth_verifier'); + $new_token = $this->data_store->new_access_token($token, $consumer, $verifier); - return $new_token; - } + return $new_token; + } - /** - * verify an api call, checks all the parameters - */ - public function verify_request(&$request) - { - $this->get_version($request); - $consumer = $this->get_consumer($request); - $token = $this->get_token($request, $consumer, "access"); - $this->check_signature($request, $consumer, $token); - return [$consumer, $token]; - } + /** + * verify an api call, checks all the parameters + * + * @param OAuthRequest $request + * @return array + * @throws OAuthException + */ + public function verify_request(OAuthRequest $request) + { + $this->get_version($request); + $consumer = $this->get_consumer($request); + $token = $this->get_token($request, $consumer, "access"); + $this->check_signature($request, $consumer, $token); + return [$consumer, $token]; + } - // Internals from here - /** - * version 1 - */ - private function get_version(&$request) - { - $version = $request->get_parameter("oauth_version"); - if (!$version) { - // Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. - // Chapter 7.0 ("Accessing Protected Ressources") - $version = '1.0'; - } - if ($version !== $this->version) { - throw new OAuthException("OAuth version '$version' not supported"); - } - return $version; - } + // Internals from here - /** - * figure out the signature with some defaults - */ - private function get_signature_method(&$request) - { - $signature_method = - @$request->get_parameter("oauth_signature_method"); + /** + * version 1 + * + * @param OAuthRequest $request + * @return string + * @throws OAuthException + */ + private function get_version(OAuthRequest $request) + { + $version = $request->get_parameter("oauth_version"); + if (!$version) { + // Service Providers MUST assume the protocol version to be 1.0 if this parameter is not present. + // Chapter 7.0 ("Accessing Protected Ressources") + $version = '1.0'; + } + if ($version !== $this->version) { + throw new OAuthException("OAuth version '$version' not supported"); + } + return $version; + } - if (!$signature_method) { - // According to chapter 7 ("Accessing Protected Ressources") the signature-method - // parameter is required, and we can't just fallback to PLAINTEXT - throw new OAuthException('No signature method parameter. This parameter is required'); - } + /** + * figure out the signature with some defaults + * + * @param OAuthRequest $request + * @return OAuthSignatureMethod + * @throws OAuthException + */ + private function get_signature_method(OAuthRequest $request) + { + $signature_method = + @$request->get_parameter("oauth_signature_method"); - if (!in_array( - $signature_method, - array_keys($this->signature_methods) - )) { - throw new OAuthException( - "Signature method '$signature_method' not supported " . - "try one of the following: " . - implode(", ", array_keys($this->signature_methods)) - ); - } - return $this->signature_methods[$signature_method]; - } + if (!$signature_method) { + // According to chapter 7 ("Accessing Protected Ressources") the signature-method + // parameter is required, and we can't just fallback to PLAINTEXT + throw new OAuthException('No signature method parameter. This parameter is required'); + } - /** - * try to find the consumer for the provided request's consumer key - */ - private function get_consumer(&$request) - { - $consumer_key = @$request->get_parameter("oauth_consumer_key"); - if (!$consumer_key) { - throw new OAuthException("Invalid consumer key"); - } + if (!in_array( + $signature_method, + array_keys($this->signature_methods) + )) { + throw new OAuthException( + "Signature method '$signature_method' not supported " . + "try one of the following: " . + implode(", ", array_keys($this->signature_methods)) + ); + } + return $this->signature_methods[$signature_method]; + } - $consumer = $this->data_store->lookup_consumer($consumer_key); - if (!$consumer) { - throw new OAuthException("Invalid consumer"); - } + /** + * try to find the consumer for the provided request's consumer key + * + * @param OAuthRequest $request + * @return OAuthConsumer + * @throws OAuthException + */ + private function get_consumer(OAuthRequest $request) + { + $consumer_key = @$request->get_parameter("oauth_consumer_key"); + if (!$consumer_key) { + throw new OAuthException("Invalid consumer key"); + } - return $consumer; - } + $consumer = $this->data_store->lookup_consumer($consumer_key); + if (!$consumer) { + throw new OAuthException("Invalid consumer"); + } - /** - * try to find the token for the provided request's token key - */ - private function get_token(&$request, $consumer, $token_type = "access") - { - $token_field = @$request->get_parameter('oauth_token'); - $token = $this->data_store->lookup_token( - $consumer, - $token_type, - $token_field - ); - if (!$token) { - throw new OAuthException("Invalid $token_type token: $token_field"); - } - return $token; - } + return $consumer; + } - /** - * all-in-one function to check the signature on a request - * should guess the signature method appropriately - */ - private function check_signature(&$request, $consumer, $token) - { - // this should probably be in a different method - $timestamp = @$request->get_parameter('oauth_timestamp'); - $nonce = @$request->get_parameter('oauth_nonce'); + /** + * try to find the token for the provided request's token key + * + * @param OAuthRequest $request + * @param $consumer + * @param string $token_type + * @return OAuthToken|null + * @throws OAuthException + */ + private function get_token(OAuthRequest &$request, $consumer, $token_type = "access") + { + $token_field = @$request->get_parameter('oauth_token'); + $token = $this->data_store->lookup_token( + $consumer, + $token_type, + $token_field + ); + if (!$token) { + throw new OAuthException("Invalid $token_type token: $token_field"); + } + return $token; + } - $this->check_timestamp($timestamp); - $this->check_nonce($consumer, $token, $nonce, $timestamp); + /** + * all-in-one function to check the signature on a request + * should guess the signature method appropriately + * + * @param OAuthRequest $request + * @param OAuthConsumer $consumer + * @param OAuthToken|null $token + * @throws OAuthException + */ + private function check_signature(OAuthRequest $request, OAuthConsumer $consumer, OAuthToken $token = null) + { + // this should probably be in a different method + $timestamp = @$request->get_parameter('oauth_timestamp'); + $nonce = @$request->get_parameter('oauth_nonce'); - $signature_method = $this->get_signature_method($request); + $this->check_timestamp($timestamp); + $this->check_nonce($consumer, $token, $nonce, $timestamp); - $signature = $request->get_parameter('oauth_signature'); - $valid_sig = $signature_method->check_signature( - $request, - $consumer, - $token, - $signature - ); + $signature_method = $this->get_signature_method($request); + + $signature = $request->get_parameter('oauth_signature'); + $valid_sig = $signature_method->check_signature( + $request, + $consumer, + $token, + $signature + ); - if (!$valid_sig) { - throw new OAuthException("Invalid signature"); - } - } + if (!$valid_sig) { + throw new OAuthException("Invalid signature"); + } + } - /** - * check that the timestamp is new enough - */ - private function check_timestamp($timestamp) - { - if (!$timestamp) - throw new OAuthException( - 'Missing timestamp parameter. The parameter is required' - ); + /** + * check that the timestamp is new enough + * + * @param int $timestamp + * @throws OAuthException + */ + private function check_timestamp($timestamp) + { + if (!$timestamp) + throw new OAuthException( + 'Missing timestamp parameter. The parameter is required' + ); - // verify that timestamp is recentish - $now = time(); - if (abs($now - $timestamp) > $this->timestamp_threshold) { - throw new OAuthException( - "Expired timestamp, yours $timestamp, ours $now" - ); - } - } + // verify that timestamp is recentish + $now = time(); + if (abs($now - $timestamp) > $this->timestamp_threshold) { + throw new OAuthException( + "Expired timestamp, yours $timestamp, ours $now" + ); + } + } - /** - * check that the nonce is not repeated - */ - private function check_nonce($consumer, $token, $nonce, $timestamp) - { - if (!$nonce) - throw new OAuthException( - 'Missing nonce parameter. The parameter is required' - ); + /** + * check that the nonce is not repeated + * + * @param OAuthConsumer $consumer + * @param OAuthToken $token + * @param string $nonce + * @param int $timestamp + * @throws OAuthException + */ + private function check_nonce(OAuthConsumer $consumer, OAuthToken $token, $nonce, int $timestamp) + { + if (!$nonce) + throw new OAuthException( + 'Missing nonce parameter. The parameter is required' + ); - // verify that the nonce is uniqueish - $found = $this->data_store->lookup_nonce( - $consumer, - $token, - $nonce, - $timestamp - ); - if ($found) { - throw new OAuthException("Nonce already used: $nonce"); - } - } + // verify that the nonce is uniqueish + $found = $this->data_store->lookup_nonce( + $consumer, + $token, + $nonce, + $timestamp + ); + if ($found) { + throw new OAuthException("Nonce already used: $nonce"); + } + } } class OAuthDataStore { - function lookup_consumer($consumer_key) - { - // implement me - } + function lookup_consumer($consumer_key) + { + // implement me + } - function lookup_token($consumer, $token_type, $token) - { - // implement me - } + function lookup_token(OAuthConsumer $consumer, $token_type, $token_id) + { + // implement me + } - function lookup_nonce($consumer, $token, $nonce, $timestamp) - { - // implement me - } + function lookup_nonce(OAuthConsumer $consumer, OAuthToken $token, $nonce, int $timestamp) + { + // implement me + } - function new_request_token($consumer, $callback = null) - { - // return a new token attached to this consumer - } + function new_request_token(OAuthConsumer $consumer, $callback = null) + { + // return a new token attached to this consumer + } - function new_access_token($token, $consumer, $verifier = null) - { - // return a new access token attached to this consumer - // for the user associated with this token if the request token - // is authorized - // should also invalidate the request token - } + function new_access_token(OAuthToken $token, OAuthConsumer $consumer, $verifier = null) + { + // return a new access token attached to this consumer + // for the user associated with this token if the request token + // is authorized + // should also invalidate the request token + } } class OAuthUtil { - public static function urlencode_rfc3986($input) - { - if (is_array($input)) { - return array_map(['OAuthUtil', 'urlencode_rfc3986'], $input); - } else if (is_scalar($input)) { - return str_replace( - '+', - ' ', - str_replace('%7E', '~', rawurlencode($input)) - ); - } else { - return ''; - } - } + public static function urlencode_rfc3986($input) + { + if (is_array($input)) { + return array_map(['OAuthUtil', 'urlencode_rfc3986'], $input); + } else if (is_scalar($input)) { + return str_replace( + '+', + ' ', + str_replace('%7E', '~', rawurlencode($input)) + ); + } else { + return ''; + } + } - // This decode function isn't taking into consideration the above - // modifications to the encoding process. However, this method doesn't - // seem to be used anywhere so leaving it as is. - public static function urldecode_rfc3986($string) - { - return urldecode($string); - } + // This decode function isn't taking into consideration the above + // modifications to the encoding process. However, this method doesn't + // seem to be used anywhere so leaving it as is. + public static function urldecode_rfc3986($string) + { + return urldecode($string); + } - // Utility function for turning the Authorization: header into - // parameters, has to do some unescaping - // Can filter out any non-oauth parameters if needed (default behaviour) - public static function split_header($header, $only_allow_oauth_parameters = true) - { - $pattern = '/(([-_a-z]*)=("([^"]*)"|([^,]*)),?)/'; - $offset = 0; - $params = []; - while (preg_match($pattern, $header, $matches, PREG_OFFSET_CAPTURE, $offset) > 0) { - $match = $matches[0]; - $header_name = $matches[2][0]; - $header_content = (isset($matches[5])) ? $matches[5][0] : $matches[4][0]; - if (preg_match('/^oauth_/', $header_name) || !$only_allow_oauth_parameters) { - $params[$header_name] = OAuthUtil::urldecode_rfc3986($header_content); - } - $offset = $match[1] + strlen($match[0]); - } + // Utility function for turning the Authorization: header into + // parameters, has to do some unescaping + // Can filter out any non-oauth parameters if needed (default behaviour) + public static function split_header($header, $only_allow_oauth_parameters = true) + { + $pattern = '/(([-_a-z]*)=("([^"]*)"|([^,]*)),?)/'; + $offset = 0; + $params = []; + while (preg_match($pattern, $header, $matches, PREG_OFFSET_CAPTURE, $offset) > 0) { + $match = $matches[0]; + $header_name = $matches[2][0]; + $header_content = (isset($matches[5])) ? $matches[5][0] : $matches[4][0]; + if (preg_match('/^oauth_/', $header_name) || !$only_allow_oauth_parameters) { + $params[$header_name] = OAuthUtil::urldecode_rfc3986($header_content); + } + $offset = $match[1] + strlen($match[0]); + } - if (isset($params['realm'])) { - unset($params['realm']); - } + if (isset($params['realm'])) { + unset($params['realm']); + } - return $params; - } + return $params; + } - // helper to try to sort out headers for people who aren't running apache - public static function get_headers() - { - if (function_exists('apache_request_headers')) { - // we need this to get the actual Authorization: header - // because apache tends to tell us it doesn't exist - $headers = apache_request_headers(); + // helper to try to sort out headers for people who aren't running apache + public static function get_headers() + { + if (function_exists('apache_request_headers')) { + // we need this to get the actual Authorization: header + // because apache tends to tell us it doesn't exist + $headers = apache_request_headers(); - // sanitize the output of apache_request_headers because - // we always want the keys to be Cased-Like-This and arh() - // returns the headers in the same case as they are in the - // request - $out = []; - foreach ($headers as $key => $value) { - $key = str_replace( - " ", - "-", - ucwords(strtolower(str_replace("-", " ", $key))) - ); - $out[$key] = $value; - } - } else { - // otherwise we don't have apache and are just going to have to hope - // that $_SERVER actually contains what we need - $out = []; - if (isset($_SERVER['CONTENT_TYPE'])) - $out['Content-Type'] = $_SERVER['CONTENT_TYPE']; - if (isset($_ENV['CONTENT_TYPE'])) - $out['Content-Type'] = $_ENV['CONTENT_TYPE']; + // sanitize the output of apache_request_headers because + // we always want the keys to be Cased-Like-This and arh() + // returns the headers in the same case as they are in the + // request + $out = []; + foreach ($headers as $key => $value) { + $key = str_replace( + " ", + "-", + ucwords(strtolower(str_replace("-", " ", $key))) + ); + $out[$key] = $value; + } + } else { + // otherwise we don't have apache and are just going to have to hope + // that $_SERVER actually contains what we need + $out = []; + if (isset($_SERVER['CONTENT_TYPE'])) + $out['Content-Type'] = $_SERVER['CONTENT_TYPE']; + if (isset($_ENV['CONTENT_TYPE'])) + $out['Content-Type'] = $_ENV['CONTENT_TYPE']; - foreach ($_SERVER as $key => $value) { - if (substr($key, 0, 5) == "HTTP_") { - // this is chaos, basically it is just there to capitalize the first - // letter of every word that is not an initial HTTP and strip HTTP - // code from przemek - $key = str_replace( - " ", - "-", - ucwords(strtolower(str_replace("_", " ", substr($key, 5)))) - ); - $out[$key] = $value; - } - } - } - return $out; - } + foreach ($_SERVER as $key => $value) { + if (substr($key, 0, 5) == "HTTP_") { + // this is chaos, basically it is just there to capitalize the first + // letter of every word that is not an initial HTTP and strip HTTP + // code from przemek + $key = str_replace( + " ", + "-", + ucwords(strtolower(str_replace("_", " ", substr($key, 5)))) + ); + $out[$key] = $value; + } + } + } + return $out; + } - // This function takes a input like a=b&a=c&d=e and returns the parsed - // parameters like this - // array('a' => array('b','c'), 'd' => 'e') - public static function parse_parameters($input) - { - if (!isset($input) || !$input) return array(); + // This function takes a input like a=b&a=c&d=e and returns the parsed + // parameters like this + // array('a' => array('b','c'), 'd' => 'e') + public static function parse_parameters($input) + { + if (!isset($input) || !$input) return array(); - $pairs = explode('&', $input); + $pairs = explode('&', $input); - $parsed_parameters = []; - foreach ($pairs as $pair) { - $split = explode('=', $pair, 2); - $parameter = OAuthUtil::urldecode_rfc3986($split[0]); - $value = isset($split[1]) ? OAuthUtil::urldecode_rfc3986($split[1]) : ''; + $parsed_parameters = []; + foreach ($pairs as $pair) { + $split = explode('=', $pair, 2); + $parameter = OAuthUtil::urldecode_rfc3986($split[0]); + $value = isset($split[1]) ? OAuthUtil::urldecode_rfc3986($split[1]) : ''; - if (isset($parsed_parameters[$parameter])) { - // We have already recieved parameter(s) with this name, so add to the list - // of parameters with this name + if (isset($parsed_parameters[$parameter])) { + // We have already recieved parameter(s) with this name, so add to the list + // of parameters with this name - if (is_scalar($parsed_parameters[$parameter])) { - // This is the first duplicate, so transform scalar (string) into an array - // so we can add the duplicates - $parsed_parameters[$parameter] = [$parsed_parameters[$parameter]]; - } + if (is_scalar($parsed_parameters[$parameter])) { + // This is the first duplicate, so transform scalar (string) into an array + // so we can add the duplicates + $parsed_parameters[$parameter] = [$parsed_parameters[$parameter]]; + } - $parsed_parameters[$parameter][] = $value; - } else { - $parsed_parameters[$parameter] = $value; - } - } - return $parsed_parameters; - } + $parsed_parameters[$parameter][] = $value; + } else { + $parsed_parameters[$parameter] = $value; + } + } + return $parsed_parameters; + } - public static function build_http_query($params) - { - if (!$params) return ''; + public static function build_http_query($params) + { + if (!$params) return ''; - // Urlencode both keys and values - $keys = OAuthUtil::urlencode_rfc3986(array_keys($params)); - $values = OAuthUtil::urlencode_rfc3986(array_values($params)); - $params = array_combine($keys, $values); + // Urlencode both keys and values + $keys = OAuthUtil::urlencode_rfc3986(array_keys($params)); + $values = OAuthUtil::urlencode_rfc3986(array_values($params)); + $params = array_combine($keys, $values); - // Parameters are sorted by name, using lexicographical byte value ordering. - // Ref: Spec: 9.1.1 (1) - uksort($params, 'strcmp'); + // Parameters are sorted by name, using lexicographical byte value ordering. + // Ref: Spec: 9.1.1 (1) + uksort($params, 'strcmp'); - $pairs = []; - foreach ($params as $parameter => $value) { - if (is_array($value)) { - // If two or more parameters share the same name, they are sorted by their value - // Ref: Spec: 9.1.1 (1) - natsort($value); - foreach ($value as $duplicate_value) { - $pairs[] = $parameter . '=' . $duplicate_value; - } - } else { - $pairs[] = $parameter . '=' . $value; - } - } - // For each parameter, the name is separated from the corresponding value by an '=' character (ASCII code 61) - // Each name-value pair is separated by an '&' character (ASCII code 38) - return implode('&', $pairs); - } + $pairs = []; + foreach ($params as $parameter => $value) { + if (is_array($value)) { + // If two or more parameters share the same name, they are sorted by their value + // Ref: Spec: 9.1.1 (1) + natsort($value); + foreach ($value as $duplicate_value) { + $pairs[] = $parameter . '=' . $duplicate_value; + } + } else { + $pairs[] = $parameter . '=' . $value; + } + } + // For each parameter, the name is separated from the corresponding value by an '=' character (ASCII code 61) + // Each name-value pair is separated by an '&' character (ASCII code 38) + return implode('&', $pairs); + } } diff --git a/src/Network/FKOAuthDataStore.php b/src/Network/FKOAuthDataStore.php index e3ee68d9c..e7a71b214 100644 --- a/src/Network/FKOAuthDataStore.php +++ b/src/Network/FKOAuthDataStore.php @@ -12,6 +12,7 @@ namespace Friendica\Network; use Friendica\Core\Config; use Friendica\Core\Logger; use Friendica\Database\DBA; +use Friendica\Util\Strings; use OAuthConsumer; use OAuthDataStore; use OAuthToken; @@ -26,15 +27,16 @@ class FKOAuthDataStore extends OAuthDataStore { /** * @return string + * @throws \Exception */ private static function genToken() { - return Friendica\Util\Strings::getRandomHex(32); + return Strings::getRandomHex(32); } /** * @param string $consumer_key key - * @return mixed + * @return OAuthConsumer|null * @throws \Exception */ public function lookup_consumer($consumer_key) @@ -52,17 +54,17 @@ class FKOAuthDataStore extends OAuthDataStore } /** - * @param string $consumer consumer - * @param string $token_type type - * @param string $token token - * @return mixed + * @param OAuthConsumer $consumer + * @param string $token_type + * @param string $token_id + * @return OAuthToken|null * @throws \Exception */ - public function lookup_token($consumer, $token_type, $token) + public function lookup_token(OAuthConsumer $consumer, $token_type, $token_id) { - Logger::log(__function__ . ":" . $consumer . ", " . $token_type . ", " . $token); + Logger::log(__function__ . ":" . $consumer . ", " . $token_type . ", " . $token_id); - $s = DBA::select('tokens', ['id', 'secret', 'scope', 'expires', 'uid'], ['client_id' => $consumer->key, 'scope' => $token_type, 'id' => $token]); + $s = DBA::select('tokens', ['id', 'secret', 'scope', 'expires', 'uid'], ['client_id' => $consumer->key, 'scope' => $token_type, 'id' => $token_id]); $r = DBA::toArray($s); if (DBA::isResult($r)) { @@ -77,14 +79,14 @@ class FKOAuthDataStore extends OAuthDataStore } /** - * @param string $consumer consumer - * @param string $token token - * @param string $nonce nonce - * @param string $timestamp timestamp + * @param OAuthConsumer $consumer + * @param OAuthToken $token + * @param string $nonce + * @param int $timestamp * @return mixed * @throws \Exception */ - public function lookup_nonce($consumer, $token, $nonce, $timestamp) + public function lookup_nonce(OAuthConsumer $consumer, OAuthToken $token, $nonce, int $timestamp) { $token = DBA::selectFirst('tokens', ['id', 'secret'], ['client_id' => $consumer->key, 'id' => $nonce, 'expires' => $timestamp]); if (DBA::isResult($token)) { @@ -95,12 +97,12 @@ class FKOAuthDataStore extends OAuthDataStore } /** - * @param string $consumer consumer - * @param string $callback optional, default null - * @return mixed + * @param OAuthConsumer $consumer + * @param string $callback + * @return OAuthToken|null * @throws \Exception */ - public function new_request_token($consumer, $callback = null) + public function new_request_token(OAuthConsumer $consumer, $callback = null) { Logger::log(__function__ . ":" . $consumer . ", " . $callback); $key = self::genToken(); @@ -131,13 +133,13 @@ class FKOAuthDataStore extends OAuthDataStore } /** - * @param string $token token - * @param string $consumer consumer - * @param string $verifier optional, defult null - * @return object - * @throws HTTPException\InternalServerErrorException + * @param OAuthToken $token token + * @param OAuthConsumer $consumer consumer + * @param string $verifier optional, defult null + * @return OAuthToken + * @throws \Exception */ - public function new_access_token($token, $consumer, $verifier = null) + public function new_access_token(OAuthToken $token, OAuthConsumer $consumer, $verifier = null) { Logger::log(__function__ . ":" . $token . ", " . $consumer . ", " . $verifier); From 2e9be55e51640810674c9311e8988a99aefa466a Mon Sep 17 00:00:00 2001 From: Hypolite Petovan Date: Thu, 5 Dec 2019 08:11:32 -0500 Subject: [PATCH 2/7] Add Mastodon API entity classes --- src/Api/Mastodon/Account.php | 86 ++++++++++++++++++++++++++++++++++++ src/Api/Mastodon/Emoji.php | 20 +++++++++ src/Api/Mastodon/Field.php | 18 ++++++++ 3 files changed, 124 insertions(+) create mode 100644 src/Api/Mastodon/Account.php create mode 100644 src/Api/Mastodon/Emoji.php create mode 100644 src/Api/Mastodon/Field.php diff --git a/src/Api/Mastodon/Account.php b/src/Api/Mastodon/Account.php new file mode 100644 index 000000000..5d4f36915 --- /dev/null +++ b/src/Api/Mastodon/Account.php @@ -0,0 +1,86 @@ +id = $contact['id']; + $account->username = $contact['nick']; + $account->acct = $contact['nick']; + $account->display_name = $contact['name']; + $account->locked = $contact['blocked']; + $account->created_at = DateTimeFormat::utc($contact['created'], DateTimeFormat::ATOM); + // No data is available from contact + $account->followers_count = 0; + $account->following_count = 0; + $account->statuses_count = 0; + $account->note = BBCode::convert($contact['about']); + $account->url = $contact['url']; + $account->avatar = $contact['avatar']; + $account->avatar_static = $contact['avatar']; + // No header picture in Friendica + $account->header = ''; + $account->header_static = ''; + // No custom emojis per account in Friendica + $account->emojis = []; + + return $account; + } +} diff --git a/src/Api/Mastodon/Emoji.php b/src/Api/Mastodon/Emoji.php new file mode 100644 index 000000000..0fda2d12c --- /dev/null +++ b/src/Api/Mastodon/Emoji.php @@ -0,0 +1,20 @@ + Date: Thu, 5 Dec 2019 08:12:59 -0500 Subject: [PATCH 3/7] Add API base module --- src/Module/Base/Api.php | 105 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 src/Module/Base/Api.php diff --git a/src/Module/Base/Api.php b/src/Module/Base/Api.php new file mode 100644 index 000000000..f3453e032 --- /dev/null +++ b/src/Module/Base/Api.php @@ -0,0 +1,105 @@ +getQueryString(), -4) === '.xml') { + self::$format = 'xml'; + } + if (substr($Arguments->getQueryString(), -4) === '.rss') { + self::$format = 'rss'; + } + if (substr($Arguments->getQueryString(), -4) === '.atom') { + self::$format = 'atom'; + } + } + + public static function post(array $parameters = []) + { + if (!api_user()) { + throw new HTTPException\UnauthorizedException(L10n::t('Permission denied.')); + } + + $a = self::getApp(); + + if (!empty($a->user['uid']) && $a->user['uid'] != api_user()) { + throw new HTTPException\ForbiddenException(L10n::t('Permission denied.')); + } + } + + /** + * Log in user via OAuth1 or Simple HTTP Auth. + * Simple Auth allow username in form of 
user@server
, ignoring server part + * + * @brief Login API user + * + * @throws HTTPException\ForbiddenException + * @throws HTTPException\UnauthorizedException + * @throws HTTPException\InternalServerErrorException + * @hook 'authenticate' + * array $addon_auth + * 'username' => username from login form + * 'password' => password from login form + * 'authenticated' => return status, + * 'user_record' => return authenticated user record + */ + protected static function login() + { + api_login(self::getApp()); + + self::$current_user_id = api_user(); + } + + /** + * @brief Get user info array. + * + * @param int|string $contact_id Contact ID or URL + * @return array|bool + * @throws HTTPException\BadRequestException + * @throws HTTPException\InternalServerErrorException + * @throws HTTPException\UnauthorizedException + * @throws \ImagickException + */ + protected static function getUser($contact_id = null) + { + return api_get_user(self::getApp(), $contact_id); + } + + protected static function format($root_element, $data) + { + switch (self::$format) { + case "atom": + case "rss": + case "xml": + $ret = api_create_xml($data, $root_element); + break; + case "json": + default: + $ret = $data; + break; + } + + return $ret; + } +} From 8016cb3ceeff134896464faa1ab5f2d60ad8a6fd Mon Sep 17 00:00:00 2001 From: Hypolite Petovan Date: Thu, 5 Dec 2019 08:16:13 -0500 Subject: [PATCH 4/7] Add GET /api/v1/follow_requests Mastodon API endpoint --- src/Module/Api/Mastodon/FollowRequests.php | 79 ++++++++++++++++++++++ static/routes.config.php | 6 ++ 2 files changed, 85 insertions(+) create mode 100644 src/Module/Api/Mastodon/FollowRequests.php diff --git a/src/Module/Api/Mastodon/FollowRequests.php b/src/Module/Api/Mastodon/FollowRequests.php new file mode 100644 index 000000000..515dc451c --- /dev/null +++ b/src/Module/Api/Mastodon/FollowRequests.php @@ -0,0 +1,79 @@ + ? AND `id` < ?', self::$current_user_id, $since_id, $max_id]; + } elseif (isset($since_id)) { + $condition = ['`uid` = ? AND NOT `self` AND `pending` AND `id` > ?', self::$current_user_id, $since_id]; + } elseif (isset($max_id)) { + $condition = ['`uid` = ? AND NOT `self` AND `pending` AND `id` < ?', self::$current_user_id, $max_id]; + } else { + $condition = ['`uid` = ? AND NOT `self` AND `pending`', self::$current_user_id]; + } + + $count = DBA::count('contact', $condition); + + $contacts = Contact::selectToArray( + [], + $condition, + ['order' => ['id' => 'DESC'], 'limit' => $limit] + ); + + $return = []; + foreach ($contacts as $contact) { + $account = Account::createFromContact($contact); + + $return[] = $account; + } + + $base_query = []; + if (isset($_GET['limit'])) { + $base_query['limit'] = $limit; + } + + /** @var BaseURL $BaseURL */ + $BaseURL = self::getClass(BaseURL::class); + + $links = []; + if ($count > $limit) { + $links[] = '<' . $BaseURL->get() . '/api/v1/follow_requests?' . http_build_query($base_query + ['max_id' => $contacts[count($contacts) - 1]['id']]) . '>; rel="next"'; + } + $links[] = '<' . $BaseURL->get() . '/api/v1/follow_requests?' . http_build_query($base_query + ['since_id' => $contacts[0]['id']]) . '>; rel="prev"'; + + header('Link: ' . implode(', ', $links)); + + System::jsonExit($return); + } +} diff --git a/static/routes.config.php b/static/routes.config.php index f5b44aec2..d8113c5c5 100644 --- a/static/routes.config.php +++ b/static/routes.config.php @@ -27,6 +27,12 @@ return [ '/recovery' => [Module\TwoFactor\Recovery::class, [R::GET, R::POST]], ], + '/api' => [ + '/v1' => [ + '/follow_requests' => [Module\Api\Mastodon\FollowRequests::class, [R::GET ]], + ], + ], + '/admin' => [ '[/]' => [Module\Admin\Summary::class, [R::GET]], From c6d422a1886d4b87db438b58c2ff56bb8f528010 Mon Sep 17 00:00:00 2001 From: Hypolite Petovan Date: Thu, 5 Dec 2019 19:46:59 -0500 Subject: [PATCH 5/7] Update Module\Help to use anchor words for titles - Previous anchors are kept for links backward compatibility --- doc/Account-Basics.md | 2 +- doc/Install.md | 4 ++-- src/Module/Help.php | 18 +++++++++++------- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/doc/Account-Basics.md b/doc/Account-Basics.md index da865ad2b..5e22e8a15 100644 --- a/doc/Account-Basics.md +++ b/doc/Account-Basics.md @@ -99,7 +99,7 @@ See Also * [Profiles](help/Profiles) -* [Global Directory](help/Making-Friends#1_1) +* [Global Directory](help/Making-Friends#The+Directories) * [Groups and Privacy](help/Groups-and-Privacy) diff --git a/doc/Install.md b/doc/Install.md index 0634a5eb9..5fe63adb2 100644 --- a/doc/Install.md +++ b/doc/Install.md @@ -12,7 +12,7 @@ This kind of functionality requires a bit more of the host system than the typic Not every PHP/MySQL hosting provider will be able to support Friendica. Many will. -But **please** review the [requirements](#1_2_1) and confirm these with your hosting provider prior to installation. +But **please** review the [requirements](#Requirements) and confirm these with your hosting provider prior to installation. ## Support If you encounter installation issues, please let us know via the [helper](http://forum.friendi.ca/profile/helpers) or the [developer](https://forum.friendi.ca/profile/developers) forum or [file an issue](https://github.com/friendica/friendica/issues). @@ -108,7 +108,7 @@ Create an empty database and note the access details (hostname, username, passwo Friendica needs the permission to create and delete fields and tables in its own database. -Please check the [troubleshooting](#1_6) section if running on MySQL 5.7.17 or newer. +Please check the [troubleshooting](#Troubleshooting) section if running on MySQL 5.7.17 or newer. ### Option A: Run the installer diff --git a/src/Module/Help.php b/src/Module/Help.php index 3b3ce5870..58cc95aff 100644 --- a/src/Module/Help.php +++ b/src/Module/Help.php @@ -65,10 +65,11 @@ class Help extends BaseModule $lastLevel = 1; $idNum = [0, 0, 0, 0, 0, 0, 0]; foreach ($lines as &$line) { - if (substr($line, 0, 2) == "([^<]+?)#i', $line, $matches)) { + $level = $matches[1]; + $anchor = urlencode($matches[2]); if ($level < $lastLevel) { for ($k = $level; $k < $lastLevel; $k++) { $toc .= ""; @@ -84,10 +85,13 @@ class Help extends BaseModule } $idNum[$level] ++; + + $href = $a->getBaseURL() . "/help/{$filename}#{$anchor}"; + $toc .= "
  • " . strip_tags($line) . "
    • "; $id = implode("_", array_slice($idNum, 1, $level)); - $href = $a->getBaseURL() . "/help/{$filename}#{$id}"; - $toc .= "
  • " . strip_tags($line) . "
    • "; - $line = "" . $line; + $line = "" . $line; + $line = "" . $line; + $lastLevel = $level; } } From e1ba53fec3391e40565e0c7c88a23cb6dae3dc4e Mon Sep 17 00:00:00 2001 From: Hypolite Petovan Date: Mon, 9 Dec 2019 22:36:52 -0500 Subject: [PATCH 6/7] Rework API documentation - Split API pages by target software - Added API entities list --- doc/API-Entities.md | 1458 +++++++++++++++++++++++++++++++++++++++++ doc/API-Friendica.md | 682 +++++++++++++++++++ doc/API-GNU-Social.md | 81 +++ doc/API-Mastodon.md | 24 + doc/API-Twitter.md | 298 +++++++++ doc/api.md | 1443 +--------------------------------------- 6 files changed, 2564 insertions(+), 1422 deletions(-) create mode 100644 doc/API-Entities.md create mode 100644 doc/API-Friendica.md create mode 100644 doc/API-GNU-Social.md create mode 100644 doc/API-Mastodon.md create mode 100644 doc/API-Twitter.md diff --git a/doc/API-Entities.md b/doc/API-Entities.md new file mode 100644 index 000000000..da59de77b --- /dev/null +++ b/doc/API-Entities.md @@ -0,0 +1,1458 @@ +# Friendica API entities + +* [Home](help) + * [Using the APIs](help/api) + + +## Activities + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    likeList of ContactsNo
    dislikeList of ContactsNo
    attendyesList of ContactsNo
    attendnoList of ContactsNo
    attendmaybeList of ContactsNo
    + +## Attachment + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    urlString (URL)No
    mimetypeStringNo
    sizeInteger (bytes)No
    + +## Contact + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    idIntegerNo
    id_strStringNo
    nameStringNo
    screen_nameStringNo
    locationStringNo
    descriptionStringNo
    profile_image_urlString (URL)No
    profile_image_url_httpsString (URL)No
    profile_image_url_profile_sizeString (URL)No
    profile_image_url_largeString (URL)No
    urlString (URL)No
    protectedBooleanNo
    followers_countIntegerNo
    friends_countIntegerNo
    listed_countIntegerNo
    favourites_countIntegerNo
    statuses_countIntegerNo
    created_atString (Date)
    +Ex: Wed May 23 06:01:13 +0000 2007 +    		No
    utc_offsetIntegerNo
    time_zoneStringNo
    geo_enabledBooleanNo
    verifiedBooleanNo
    langStringNo
    contributors_enabledBooleanNo
    is_translatorBooleanNo
    is_translation_enabledBooleanNo
    followingBooleanNo
    follow_request_sentBooleanNo
    statusnet_blockingBooleanNo
    notificationsBooleanNo
    statusnet_profile_urlString (URL)No
    uidIntegerNo
    cidIntegerNo
    pidIntegerNo
    selfIntegerNo
    networkStringNo
    + + +## Entities + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    hashtagsList of HashtagsNo
    symbolsList of SymbolsNo
    urlsList of URLsNo
    user_mentionsList of User mentionsNo
    mediaList of MediasNo
    + +## Hashtag + +Unused + +## Item + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    textString (Plaintext)No
    truncatedBooleanNo
    created_atString (Date)
    +Ex: Wed May 23 06:01:13 +0000 2007 +    		No
    in_reply_to_status_idIntegerNo
    in_reply_to_status_id_strStringNo
    sourceStringNo
    idIntegerNo
    id_strStringNo
    in_reply_to_user_idIntegerNo
    in_reply_to_user_id_strStringNo
    in_reply_to_screen_nameStringNo
    geoStringYes
    favoritedBooleanNo
    userContactNo
    friendica_authorContactNo
    friendica_owner + +ContactNo
    friendica_privateBooleanNo
    statusnet_htmlString (HTML)No
    statusnet_conversation_idIntegerNo
    external_urlString (URL)No
    friendica_activitiesActivitiesNo
    friendica_titleString (Plaintext)No
    friendica_htmlString (HTML)No
    attachmentsList of AttachmentsYes
    entitiesEntitiesYes
    + +## Media + +Identical to [the Twitter Media Object](https://developer.twitter.com/en/docs/tweets/data-dictionary/overview/entities-object#media). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    idIntegerNo
    id_strStringNo
    indicesList of IntegerNo
    media_urlString (URL)No
    media_url_httpsString (URL)No
    urlString (URL)No
    display_urlString (URL)No
    expanded_urlString (URL)No
    ext_alt_textStringNo
    typeStringNo
    sizesSizesNo
    + +## Notification + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeDescription
    idInteger
    hashString
    typeInteger
      +
    • 1: Inbound follow request
      • +
    • 2: Outbound follow request confirmation
      • +
    • 4: Wall-to-wall post
      • +
    • 8: Reply
      • +
    • 16: Private message
      • +
    • 32: Friend suggestion
      • +
    • 64: Unused
      • +
    • 128: Mention
      • +
    • 256: Tag added to a post
      • +
    • 512: Poke
      • +
    • 1024: New post
      • +
    • 16384: System email
      • +
    • 32768: System event
      • +
    nameStringFull name of the contact subject
    urlString (URL)Profile page URL of the contact subject
    photoString (URL)Profile photo URL of the contact subject
    dateString (Date)YYYY-MM-DD hh:mm:ss local server time
    msgString (BBCode)
    uidIntegerOwner User Id
    linkString (URL)Notification URL
    iidIntegerItem Id
    parentIntegerParent Item Id
    seenInteger (Boolean)Whether the notification was read or not.
    verbString (URL)[Activity Streams](http://activitystrea.ms) Verb URL
    seenInteger (Boolean)Whether the notification was read or not.
    otypeEnumSubject type (`item`, `intro` or `mail`)
    name_cacheString (HTML)Full name of the contact subject
    msg_cacheString (Plaintext)Plaintext version of the notification text with a placeholder (`{0}`) for the subject contact's name.
    timestampIntegerUnix timestamp
    date_relStringTime since the note was posted, eg "1 hour ago"
    msg_htmlString (HTML)
    msg_plainString (Plaintext)
    + +## Photo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeDescription
    idStringResource ID (32 hex chars)
    createdString (Date)Format YYYY-MM-DD HH:MM:SS
    editedString (Date)Format YYYY-MM-DD HH:MM:SS
    titleString
    descString (Plaintext)Picture caption
    albumStringAlbum name
    filenameStringOriginal image filename
    typeStringMIME Type
    heightIntegerImage height in pixels
    widthIntegerImage width in pixels
    profileInteger1 if it is a profile photo
    allow_cidString (ACL)List of contact ids wrapped in angle brackets allowed to access the photo.
    allow_gidString (ACL)List of contact group ids wrapped in angle brackets allowed to access the photo.
    deny_cidString (ACL)List of contact ids wrapped in angle brackets forbidden to access the photo.
    deny_gidString (ACL)List of contact group ids wrapped in angle brackets forbidden to access the photo.
    linkArray of Strings (URL) +URLs to the different scales indexed by scale number if no specific scale was requested. +Mutually exclusive with data datasize. +
    datasizeInteger +Picture size in bytes if a single scale was requested. +Mutually exclusive with link. +
    dataString +Base64-encoded image data if a single scale was requested. +Mutually exclusive with link. +
    friendica_activitiesActivities
    friendica_commentsList of Items
    rights_mismatchBooleanTrue if the ACL differs between the picture and the associated item.
    + +## Photo List Item + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeDescription
    idStringResource ID (32 hex chars)
    albumStringAlbum name
    filenameStringOriginal image filename
    typeStringMIME Type
    createdString (Date)Format YYYY-MM-DD HH:MM:SS
    editedString (Date)Format YYYY-MM-DD HH:MM:SS
    descString (Plaintext)Picture caption
    thumbString (URL)URL of the smallest scale version of the picture.
    + +## Private message + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeDescription
    idInteger
    sender_idIntegerSender Contact Id
    textStringCan be HTML or plaintext depending on the API call parameter `getText`.
    recipient_idIntegerRecipient Contact Id
    created_atString (Date)Ex: Wed May 23 06:01:13 +0000 2007
    sender_screen_nameString
    recipient_screen_nameString
    senderContact
    recipientContact
    titleStringEmpty if the API call parameter `getText` is empty or absent.
    friendica_seenInteger (Boolean)Whether the private message has been read or not.
    friendica_parent_uriString
    + +## Profile + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeDescription
    profile_idInteger
    profile_nameString
    is_defaultBoolean
    hide_friendsBooleanWhether the user chose to hide their contact list on their profile.
    profile_photoString (URL)Largest size profile picture URL.
    profile_thumbString (URL)Smallest size profile picture URL.
    publishBooleanWhether the user chose to publish their profile in the local directory.
    net_publishBooleanWhether the user chose to publish their profile in the global directory.
    descriptionString
    date_of_birthString
    addressString
    cityString
    regionString
    postal_codeString
    countryString
    hometownString
    genderString
    maritalString
    marital_withString
    marital_sinceString (Date)
    sexualString
    politicString
    religionString
    public_keywordsStringComma-separated list of words meant to be displayed as hashtags.
    private_keywordsStringComma-separated list of words meant to be used for search only.
    likesString (Plaintext)
    dislikesString (Plaintext)
    aboutString (Plaintext)
    musicString (Plaintext)
    bookString (Plaintext)
    tvString (Plaintext)
    filmString (Plaintext)
    interestString (Plaintext)
    romanceString (Plaintext)
    workString (Plaintext)
    educationString (Plaintext)
    social_networksString (Plaintext)
    homepageString (URL)
    usersList of ContactsIf populated, only these contacts have access to the profile.
    + +## Size + + + + + + + + + + +
    AttributeTypeNullable
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    wIntegerNo
    hIntegerNo
    resizeEnum (fit, crop)Yes
    + + +## Sizes + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    mediumSizeNo
    largeSizeYes
    thumbSizeYes
    smallSizeYes
    + +## Symbol + +Unused + +## URL + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeTypeNullable
    urlString (URL)No
    expanded_urlString (URL)No
    display_urlString (URL)No
    indicesList of IntegerNo
    + +## User Mention + +Unused \ No newline at end of file diff --git a/doc/API-Friendica.md b/doc/API-Friendica.md new file mode 100644 index 000000000..2e33a887d --- /dev/null +++ b/doc/API-Friendica.md @@ -0,0 +1,682 @@ +# Friendica API + +* [Home](help) + * [Using the APIs](help/api) + +## Overview + +Friendica provides the following specific endpoints. + +Authentication is the same as described in [Using the APIs](help/api#Authentication). + +## Entities + +These endpoints uses the [Friendica API entities](help/API-Entities). + +## Endpoints + +### GET api/externalprofile/show + +Returns a [Contact](help/API-Entities#Contact) entity for the provided profile URL. + +#### Parameters + +- `profileurl`: Profile URL + +### GET api/statuses/public_timeline + +Returns a list of public [Items](help/API-Entities#Item) posted on this node. +Equivalent of the local community page. + +#### Parameters + +* `count`: Items per page (default: 20) +* `page`: page number +* `since_id`: minimum id +* `max_id`: maximum id +* `exclude_replies`: don't show replies (default: false) +* `conversation_id`: Shows all statuses of a given conversation. +* `include_entities`: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters + +* `trim_user` + +### GET api/statuses/networkpublic_timeline + +Returns a list of public [Items](help/API-Entities#Item) this node is aware of. +Equivalent of the global community page. + +#### Parameters + +* `count`: Items per page (default: 20) +* `page`: page number +* `since_id`: minimum id +* `max_id`: maximum id +* `exclude_replies`: don't show replies (default: false) +* `conversation_id`: Shows all statuses of a given conversation. +* `include_entities`: "true" shows entities for pictures and links (Default: false) + +### GET api/statuses/replies + +#### Parameters + +* `count`: Items per page (default: 20) +* `page`: page number +* `since_id`: minimum id +* `max_id`: maximum id +* `include_entities`: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters + +* `include_rts` +* `trim_user` +* `contributor_details` + +--- + +### GET api/conversation/show + +Unofficial Twitter command. It shows all direct answers (excluding the original post) to a given id. + +#### Parameters + +* `id`: id of the post +* `count`: Items per page (default: 20) +* `page`: page number +* `since_id`: minimum id +* `max_id`: maximum id +* `include_entities`: "true" shows entities for pictures and links (Default: false) + +#### Unsupported parameters + +* `include_rts` +* `trim_user` +* `contributor_details` + +### GET api/statusnet/conversation + +Alias of [`api/conversation/show`](#GET+api%2Fconversation%2Fshow). + +### GET api/statusnet/config + +Returns the public Friendica node configuration. + +### GET api/gnusocial/config + +Alias of [`api/statusnet/config`](#GET+api%2Fstatusnet%2Fconfig). + +### GET api/statusnet/version + +Returns a fake static StatusNet protocol version. + +### GET api/gnusocial/version + +Alias of [`api/statusnet/version`](#GET+api%2Fstatusnet%2Fversion). + +--- + +### POST api/friendica/activity/[verb] + +Add or remove an activity from an item. +'verb' can be one of: + +* `like` +* `dislike` +* `attendyes` +* `attendno` +* `attendmaybe` + +To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike" +Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes". +Attend verbs should be used only with event-related items (there is no check at the moment). + +#### Parameters + +* `id`: item id + +#### Return values + +On success: +json: + +```"ok"``` + +xml: + +```true``` + +On error: +HTTP 400 BadRequest + +--- + +### GET api/direct_messages + +Deprecated Twitter received direct message list endpoint. + +#### Parameters + +* `count`: Items per page (default: 20) +* `page`: page number +* `since_id`: minimum 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` + +### GET api/direct_messages/all + +Returns all [Private Messages](help/API-Entities#Private+message). + +#### Parameters + +* `count`: Items per page (default: 20) +* `page`: page number +* `since_id`: minimum 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") + +### GET api/direct_messages/conversation + +Returns all replies of a single private message conversation. Returns [Private Messages](help/API-Entities#Private+message) + +#### Parameters + +* `count`: Items per page (default: 20) +* `page`: page number +* `since_id`: minimum 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") + +### GET api/direct_messages/sent + +Deprecated Twitter sent direct message list endpoint. Returns [Private Messages](help/API-Entities#Private+message). + +#### Parameters + +* `count`: Items per page (default: 20) +* `page`: page number +* `since_id`: minimum 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") + + +### POST/PUT api/direct_messages/new + +Deprecated Twitter direct message submission endpoint. + +#### 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 + +### POST/DELETE api/direct_messages/destroy + +Deprecated Twitter direct message deletion endpoint. + +#### 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: +HTTP 400 BadRequest + +* on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"} + +### GET api/friendica/direct_messages_setseen + +#### Parameters + +* `id`: id of the message to be updated as seen + +#### Return values + +On success: + +* JSON return `{"result": "ok", "message": "message set to seen"}` + +On error: + +* different JSON returns `{"result": "error", "message": "xyz"}` + + +### GET api/friendica/direct_messages_search (GET; AUTH) + +Returns [Private Messages](help/API-Entities#Private+message) matching the provided search string. + +#### Parameters + +* `searchstring`: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored) +* `getText` (optional): `plain`|`html` If ommited, the title is prepended to the plaintext body in the `text` attribute of the private message objects. +* `getUserObjects` (optional): `true`|`false` If `false`, the `sender` and `recipient` attributes of the private message object are absent. + +#### Return values + +Returns only tested with JSON, XML might work as well. + +On success: + +* JSON return `{"success":"true", "search_results": array of found messages}` +* JSOn return `{"success":"false", "search_results": "nothing found"}` + +On error: + +* different JSON returns `{"result": "error", "message": "searchstring not specified"}` + +--- + +### GET api/friendica/group_show + +Return all or a specified group of the user with the containing contacts as array. + +#### Parameters + +* `gid`: optional, if not given, API returns all groups of the user + +#### Return values + +Array of: + +* `name`: name of the group +* `gid`: id of the group +* `user`: array of [Contacts](help/API-Entities#Contact) + +### POST/PUT api/friendica/group_create + +Create the group with the posted array of contacts as members. + +#### Parameters + +* `name`: name of the group to be created + +#### POST data + +JSON data as Array like the result of [GET api/friendica/group_show](#GET+api%2Ffriendica%2Fgroup_show): + +* `gid` +* `name` +* List of [Contacts](help/API-Entities#Contact) + +#### Return values + +Array of: + +* `success`: true if successfully created or reactivated +* `gid`: gid of the created group +* `name`: name of the created group +* `status`: "missing user" | "reactivated" | "ok" +* `wrong users`: array of users, which were not available in the contact table + +### POST api/friendica/group_update + +Update the group with the posted array of contacts as members (post all members of the group to the call; function will remove members not posted). + +#### Parameters + +* `gid`: id of the group to be changed +* `name`: name of the group to be changed + +#### POST data + +JSON data as array like the result of [GET api/friendica/group_show](#GET+api%2Ffriendica%2Fgroup_show): + +* `gid` +* `name` +* List of [Contacts](help/API-Entities#Contact) + +#### Return values + +Array of: + +* `success`: true if successfully updated +* `gid`: gid of the changed group +* `name`: name of the changed group +* `status`: "missing user" | "ok" +* `wrong users`: array of users, which were not available in the contact table + +### POST/DELETE api/friendica/group_delete + +Delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted. + +#### Parameters + +* `gid`: id of the group to be deleted +* `name`: name of the group to be deleted + +#### Return values + +Array of: + +* `success`: true if successfully deleted +* `gid`: gid of the deleted group +* `name`: name of the deleted group +* `status`: "deleted" if successfully deleted +* `wrong users`: empty array + +--- + +### GET api/friendica/notifications + +Return last 50 [Notifications](help/API-Entities#Notification) for the current user, ordered by date with unseen item on top. + +#### Parameters + +none + +### POST api/friendica/notifications/seen + +Set notification as seen. + +#### Parameters + +- `id`: id of the notification to set seen + +#### Return values + +If the note is linked to an item, returns an [Item](help/API-Entities#Item). + +Otherwise, a success status is returned: + +* `success` (json) | `success` (xml) + +--- + +### GET api/friendica/photo + +Returns a [Photo](help/API-Entities#Photo). + +#### Parameters + +* `photo_id`: Resource id of a photo. +* `scale`: (optional) scale value of the photo + +Returns data of a picture with the given resource. +If 'scale' isn't provided, returned data include full url to each scale of the photo. +If 'scale' is set, returned data include image data base64 encoded. + +possibile scale value are: + +* 0: original or max size by server settings +* 1: image with or height at <= 640 +* 2: image with or height at <= 320 +* 3: thumbnail 160x160 +* 4: Profile image at 300x300 +* 5: Profile image at 80x80 +* 6: Profile image at 48x48 + +An image used as profile image has only scale 4-6, other images only 0-3 + +#### Return values + +json: + +```json + { + "id": "photo id" + "created": "date(YYYY-MM-DD HH:MM:SS)", + "edited": "date(YYYY-MM-DD HH:MM:SS)", + "title": "photo title", + "desc": "photo description", + "album": "album name", + "filename": "original file name", + "type": "mime type", + "height": "number", + "width": "number", + "profile": "1 if is profile photo", + "link": { + "": "url to image" + ... + }, + // if 'scale' is set + "datasize": "size in byte", + "data": "base64 encoded image data" + } +``` + +xml: + +```xml + + photo id + date(YYYY-MM-DD HH:MM:SS) + date(YYYY-MM-DD HH:MM:SS) + photo title + photo description + album name + original file name + mime type + number + number + 1 if is profile photo + + + ... + + +``` + +### GET api/friendica/photos/list + +Returns the API user's [Photo List Items](help/API-Entities#Photo+List+Item). + +#### Return values + +json: + +```json + [ + { + id: "resource_id", + album: "album name", + filename: "original file name", + type: "image mime type", + thumb: "url to thumb sized image" + }, + ... + ] +``` + +xml: + +```xml + + + "url to thumb sized image" + + ... + +``` + +### POST api/friendica/photo/create + +Alias of [`api/friendica/photo/update`](#POST+api%2Ffriendica%2Fphoto%2Fupdate) + +### POST api/friendica/photo/update + +Saves data for the scales 0-2 to database (see above for scale description). +Call adds non-public entries to items table to enable authenticated contacts to comment/like the photo. +Client should pay attention to the fact that updated access rights are not transferred to the contacts. i.e. public photos remain publicly visible if they have been commented/liked before setting visibility back to a limited group. +Currently it is best to inform user that updating rights is not the right way to do this, and offer a solution to add photo as a new photo with the new rights instead. + +#### Parameters + +* `photo_id` (optional): if specified the photo with this id will be updated +* `media` (optional): image data as base64, only optional if photo_id is specified (new upload must have media) +* `desc` (optional): description for the photo, updated when photo_id is specified +* `album`: name of the album to be deleted (always necessary) +* `album_new` (optional): can be used to change the album of a single photo if photo_id is specified +* `allow_cid`/`allow_gid`/`deny_cid`/`deny_gid` (optional): + - on create: empty string or omitting = public photo, specify in format `````` for private photo + - on update: keys need to be present with empty values for changing a private photo to public + +#### Return values + +On success: + +* new photo uploaded: JSON return with photo data (see [GET api/friendica/photo](#GET+api%2Ffriendica%2Fphoto)) +* photo updated - changed photo data: JSON return with photo data (see [GET api/friendica/photo](#GET+api%2Ffriendica%2Fphoto)) +* photo updated - changed info: JSON return `{"result": "updated", "message":"Image id 'xyz' has been updated."}` +* photo updated - nothing changed: JSON return `{"result": "cancelled","message": "Nothing to update for image id 'xyz'."}` + +On error: + +* 403 FORBIDDEN: if not authenticated +* 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid" +* 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server", + "image size exceeds Friendica Config setting (uploaded size: x)", + "unable to process image data", + "image upload failed", + "unknown error - uploading photo failed, see Friendica log for more information", + "unknown error - update photo entry in database failed", + "unknown error - this error on uploading or updating a photo should never happen" + +### DELETE api/friendica/photo/delete + +Deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this +Sets item table entries for this photo to deleted = 1. + +#### Parameters + +* `photo_id`: id of the photo to be deleted + +#### Return values + +On success: + +* JSON return + +```json +{ + "result": "deleted", + "message": "photo with id 'xyz' has been deleted from server." +} +``` + +On error: + +* 403 FORBIDDEN: if not authenticated +* 400 BADREQUEST: "no photo_id specified", "photo not available" +* 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred" + +--- + +### POST/DELETE api/friendica/photoalbum/delete + +Deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this. + +#### Parameters + +* `album`: name of the album to be deleted + +#### Return values + +On success: + +* JSON return + +```json +{ + "result": "deleted", + "message": "album 'xyz' with all containing photos has been deleted." +} +``` + +On error: + +* 403 FORBIDDEN: if not authenticated +* 400 BADREQUEST: "no albumname specified", "album not available" +* 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed" + +### POST/PUT api/friendica/photoalbum/update + +Changes the album name to album_new for all photos in album. + +#### Parameters + +* `album`: name of the album to be updated +* `album_new`: new name of the album + +#### Return values + +On success: + +* JSON return + +```json +{ + "result": "updated", + "message":"album 'abc' with all containing photos has been renamed to 'xyz'." +} +``` + +On error: + +* 403 FORBIDDEN: if not authenticated +* 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available" +* 500 INTERNALSERVERERROR: "unknown error - updating in database failed" + +--- + +### GET api/friendica/profile/show + +Returns the [Profile](help/API-Entities#Profile) data of all profiles or a single profile of the authenticated user. + +#### Parameters + +* `profile_id` (optional): id of the profile to be returned. If omitted all profiles are returned by default. + +#### Return values + +On success: Array of: + +* `multi_profiles`: true if user has activated multi_profiles +* `global_dir`: URL of the global directory set in server settings +* `friendica_owner`: user data of the authenticated user +* `profiles`: array of the profile data + +On error: +HTTP 403 Forbidden: when no authentication was provided +HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user + +General description of profile data in API returns: + +--- + +### GET api/friendica/remoteauth + +Similar as /redir, redirects to `url` after DFRN authentication. + +#### Parameters + +- `c_url`: url of remote contact to auth to +- `url`: string, url to redirect after auth + +## Deprecated endpoints + +- POST api/statuses/mediap diff --git a/doc/API-GNU-Social.md b/doc/API-GNU-Social.md new file mode 100644 index 000000000..157450666 --- /dev/null +++ b/doc/API-GNU-Social.md @@ -0,0 +1,81 @@ +# GNU Social API + +* [Home](help) + * [Using the APIs](help/api) + +## Overview + +Friendica provides the following endpoints defined in [the official GNU Social Twitter-like API reference](https://gnusocial.net/doc/twitterapi). + +Authentication is the same as described in [Using the APIs](help/api#Authentication). + +## Entities + +These endpoints use the [Friendica API entities](help/API-Entities). + +## Implemented endpoints + +- GET api/account/rate_limit_status +- POST api/account/update_profile_image +- GET api/account/verify_credentials + +- GET api/direct_messages +- POST/DELETE api/direct_messages/destroy +- POST api/direct_messages/new +- GET api/direct_messages/sent +- GET api/favorites +- POST api/favorites/create/:id +- POST api/favorites/destroy/:id +- GET api/followers/ids +- POST api/friendships/destroy +- GET api/friends/ids +- GET/POST api/help/test +- POST api/oauth/access_token +- POST api/oauth/request_token +- GET api/search +- GET api/statuses/show/:id +- POST api/statuses/destroy/:id +- GET api/statuses/followers +- GET api/statuses/friends +- GET api/statuses/friends_timeline +- GET api/statuses/friends_timeline/:username +- GET api/statuses/home_timeline +- GET api/statuses/mentions +- GET api/statuses/replies +- GET api/statuses/replies/:username +- POST api/statuses/retweet/:id +- GET api/statuses/public_timeline +- POST api/statuses/update +- GET api/statuses/user_timeline +- GET api/users/show + +## Non-implemented endpoints + +- statuses/retweeted_to_me +- statuses/retweeted_by_me +- statuses/retweets_of_me +- friendships/create +- friendships/exists +- friendships/show +- account/end_session +- account/update_delivery_device +- account/update_profile_background_image +- notifications/follow +- notifications/leave +- blocks/create +- blocks/destroy +- blocks/exists +- blocks/blocking +- oauth/authorize +- statusnet/groups/timeline +- statusnet/groups/show +- statusnet/groups/create +- statusnet/groups/join +- statusnet/groups/leave +- statusnet/groups/list +- statusnet/groups/list_all +- statusnet/groups/membership +- statusnet/groups/is_member +- statusnet/tags/timeline +- statusnet/media/upload +- statusnet/config diff --git a/doc/API-Mastodon.md b/doc/API-Mastodon.md new file mode 100644 index 000000000..d885e6ab3 --- /dev/null +++ b/doc/API-Mastodon.md @@ -0,0 +1,24 @@ +# Mastodon API + +* [Home](help) + * [Using the APIs](help/api) + +## Overview + +Friendica provides the following endpoints defined in [the official Mastodon API reference](https://docs.joinmastodon.org/api/). + +Authentication is the same as described in [Using the APIs](help/api#Authentication). + +## Entities + +These endpoints use the [Mastodon API entities](https://docs.joinmastodon.org/api/entities/). + +## Implemented endpoints + +- [GET /api/v1/follow_requests](https://docs.joinmastodon.org/api/rest/follow-requests/#get-api-v1-follow-requests) + +## Non-implemented endpoints + +- [POST /api/v1/follow_requests/:id/authorize](https://docs.joinmastodon.org/api/rest/follow-requests/#post-api-v1-follow-requests-id-authorize) +- [POST /api/v1/follow_requests/:id/reject](https://docs.joinmastodon.org/api/rest/follow-requests/#post-api-v1-follow-requests-id-reject) + diff --git a/doc/API-Twitter.md b/doc/API-Twitter.md new file mode 100644 index 000000000..d352e528d --- /dev/null +++ b/doc/API-Twitter.md @@ -0,0 +1,298 @@ +# Twitter API + +* [Home](help) + * [Using the APIs](help/api) + +## Overview + +Friendica provides the following endpoints defined in the [official Twitter API reference](https://developer.twitter.com/en/docs/api-reference-index). + +Authentication is the same as described in [Using the APIs](help/api#Authentication). + +## Entities + +These endpoints use the [Friendica API entities](help/API-Entities). + +## 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. + +## Friendica-specific return values + +* `cid`: Contact id of the user (important for "contact_allow" and "contact_deny") +* `network`: network of the user + +## Unsupported parameters + +* `cursor` +* `trim_user` +* `contributor_details` +* `place_id` +* `display_coordinates` +* `include_rts`: To-Do +* `include_my_retweet`: Retweets in Friendica are implemented in a different way + +## Implemented endpoints + +- [POST api/oauth/access_token](https://developer.twitter.com/en/docs/basics/authentication/api-reference/access_token) + - Unsupported parameters: + - `x_auth_password` + - `x_auth_username` + - `x_auth_mode` +- [POST api/oauth/request_token](https://developer.twitter.com/en/docs/basics/authentication/api-reference/request_token) + - Unsupported parameter: + - `x_auth_access_type` + + +- [GET api/account/verify_credentials](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials) + - Unsupported parameter: + - `include_email` +- [POST api/account/update_profile](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile) + - Unsupported parameters: + - `url` + - `location` + - `profile_link_color` + - `include_entities` + - `skip_status` +- [POST api/account/update_profile_image](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_image) + - Additional parameter: + - `profile_id` (optional): Numerical id of the profile for which the image should be used, default is changing the default profile. + + +- [POST api/statuses/update](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update) + - Unsupported parameter: + - `display_coordinates` +- [POST api/statuses/update_with_media (deprecated)](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update_with_media) + + +- [POST api/media/upload](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload) + - Additional return value: + - `image.friendica_preview_url`: image preview url +- [POST api/media/metadata/create](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-metadata-create) + + +- [GET api/users/show](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-show) +- [GET api/users/search](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-search) + - Unsupported parameters: + - `page` + - `count` + - `include_entities` +- [GET api/users/lookup](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-lookup) + - Unsupported parameters: + - `screen_name` + - `include_entities` + + +- [GET api/search/tweets](https://developer.twitter.com/en/docs/tweets/search/api-reference/get-search-tweets) + - Unsupported parameters: + - `geocode` + - `lang` + - `locale` + - `result_type` + - `until` + - `include_entities` + + +- [GET api/saved_searches/list](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-saved_searches-list) + + +- [GET api/statuses/home_timeline](https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-home_timeline) + - Alias: `GET api/statuses/friends_timeline` +- [GET api/statuses/user_timeline](https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-user_timeline) +- [GET api/statuses/mentions (deprecated)](https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-mentions_timeline) +- [GET api/statuses/show/:id](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-show-id) +- [POST api/statuses/retweet/:id](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-retweet-id) +- [POST api/statuses/destroy/:id](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-destroy-id) +- [GET api/statuses/followers (deprecated)](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-list) + - Alias: `GET api/statuses/friends` + + +- [GET api/favorites (deprecated)](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-favorites-list) + - Unsupported parameters: + - `user_id`: Favorites aren't returned for other users than self + - `screen_name`: Favorites aren't returned for other users than self +- [POST api/favorites/create](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-create) +- [POST api/favorites/destroy](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-favorites-destroy) + + +- [GET api/lists/list](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-list) +- [GET api/lists/ownerships](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-ownerships) + - Unsupported parameters: + - `slug` + - `owner_screen_name` + - `owner_id` + - `include_entities` +- [GET api/lists/statuses](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-statuses) + - Unsupported parameters: + - `screen_name` + - `count` +- [GET api/lists/subscriptions](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscriptions) +- [POST api/lists/update](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-update) + - Unsupported parameters: + - `slug` + - `name` + - `mode` + - `description` + - `owner_screen_name` + - `owner_id` +- [POST api/lists/create](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-create) + - Unsupported parameters: + - `mode` + - `description` +- [POST api/lists/destroy](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-destroy) + - Unsupported parameters: + - `owner_screen_name` + - `owner_id` + - `slug` + +- [GET api/blocks/list](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-list) + + +- [GET api/friendships/incoming](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-incoming) + - Unsupported parameters + - `stringify_ids` +- [GET api/followers/ids](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids) + - Unsupported parameters: + - `user_id`: Relationships aren't returned for other users than self + - `screen_name`: Relationships aren't returned for other users than self +- [GET api/friends/ids](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-ids) + - Unsupported parameters: + - `user_id`: Relationships aren't returned for other users than self + - `screen_name`: Relationships aren't returned for other users than self + + +- [POST api/friendships/destroy](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-destroy) + + +## Non-implemented endpoints + +- [GET oauth/authenticate](https://developer.twitter.com/en/docs/basics/authentication/api-reference/authenticate) +- [GET oauth/authorize](https://developer.twitter.com/en/docs/basics/authentication/api-reference/authorize) +- [POST oauth/invalidate_token](https://developer.twitter.com/en/docs/basics/authentication/api-reference/invalidate_access_token) +- [POST oauth2/invalidate_token](https://developer.twitter.com/en/docs/basics/authentication/api-reference/invalidate_bearer_token) +- [POST oauth2/token](https://developer.twitter.com/en/docs/basics/authentication/api-reference/token) + + +- [GET lists/members](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members) +- [GET lists/members/show](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-members-show) +- [GET lists/memberships](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-memberships) +- [GET lists/show](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-show) +- [GET lists/subscribers](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers) +- [GET lists/subscribers/show](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/get-lists-subscribers-show) +- [POST lists/members/create](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create) +- [POST lists/members/create_all](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-create_all) +- [POST lists/members/destroy](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy) +- [POST lists/members/destroy_all](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-members-destroy_all) +- [POST lists/subscribers/create](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-create) +- [POST lists/subscribers/destroy](https://developer.twitter.com/en/docs/accounts-and-users/create-manage-lists/api-reference/post-lists-subscribers-destroy) + + +- [GET followers/list](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-followers-list) +- [GET friends/list](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friends-list) +- [GET friendships/lookup](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-lookup) +- [GET friendships/no_retweets/ids](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-no_retweets-ids) +- [GET friendships/outgoing](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-outgoing) +- [GET friendships/show](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-friendships-show) +- [GET users/suggestions (deprecated)](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions) +- [GET users/suggestions/:slug (deprecated)](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug) +- [GET users/suggestions/:slug/members (deprecated)](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/get-users-suggestions-slug-members) +- [POST friendships/create](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-create) +- [POST friendships/update](https://developer.twitter.com/en/docs/accounts-and-users/follow-search-get-users/api-reference/post-friendships-update) + + +- [GET account/settings](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-account-settings) +- [GET saved_searches/show/:id](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-saved_searches-show-id) +- [GET users/profile_banner](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/get-users-profile_banner) +- [POST account/remove_profile_banner](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-remove_profile_banner) +- [POST account/settings](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-settings) +- [POST account/update_profile_background_image (deprecated)](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_background_image) +- [POST account/update_profile_banner](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-account-update_profile_banner) +- [POST saved_searches/create](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-saved_searches-create) +- [POST saved_searches/destroy/:id](https://developer.twitter.com/en/docs/accounts-and-users/manage-account-settings/api-reference/post-saved_searches-destroy-id) + + +- [GET blocks/ids](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-blocks-ids) +- [GET mutes/users/ids](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-ids) +- [GET mutes/users/list](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/get-mutes-users-list) +- [POST blocks/create](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-create) +- [POST blocks/destroy](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-blocks-destroy) +- [POST mutes/users/create](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-create) +- [POST mutes/users/destroy](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-mutes-users-destroy) +- [POST users/report_spam](https://developer.twitter.com/en/docs/accounts-and-users/mute-block-report-users/api-reference/post-users-report_spam) + + +- [GET collections/entries](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/get-collections-entries) +- [GET collections/list](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/get-collections-list) +- [GET collections/show](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/get-collections-show) +- [POST collections/create](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-create) +- [POST collections/destroy](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-destroy) +- [POST collections/entries/add](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-add) +- [POST collections/entries/curate](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-curate) +- [POST collections/entries/move](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-move) +- [POST collections/entries/remove](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-entries-remove) +- [POST collections/update](https://developer.twitter.com/en/docs/tweets/curate-a-collection/api-reference/post-collections-update) + + +- [POST statuses/filter](https://developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter) + + +- [GET statuses/mentions_timeline](https://developer.twitter.com/en/docs/tweets/timelines/api-reference/get-statuses-mentions_timeline) + + +- [GET favorites/list](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-favorites-list) +- [GET statuses/lookup](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-lookup) +- [GET statuses/oembed](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-oembed) +- [GET statuses/retweeters/ids](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweeters-ids) +- [GET statuses/retweets/:id](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets-id) +- [GET statuses/retweets_of_me](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/get-statuses-retweets_of_me) +- [POST statuses/unretweet/:id](https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-unretweet-id) + + +- [GET statuses/sample](https://developer.twitter.com/en/docs/tweets/sample-realtime/api-reference/get-statuses-sample) + + +- [GET compliance/firehose](https://developer.twitter.com/en/docs/tweets/compliance/api-reference/compliance-firehose) + + +- [DELETE custom_profiles/destroy.json](https://developer.twitter.com/en/docs/direct-messages/custom-profiles/api-reference/delete-profile) +- [GET custom_profiles/:id](https://developer.twitter.com/en/docs/direct-messages/custom-profiles/api-reference/get-profile) +- [GET custom_profiles/list](https://developer.twitter.com/en/docs/direct-messages/custom-profiles/api-reference/get-profile-list) +- [POST custom_profiles/new.json](https://developer.twitter.com/en/docs/direct-messages/custom-profiles/api-reference/new-profile) + + +- [DELETE direct_messages/events/destroy](https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/delete-message-event) +- [GET direct_messages/events/list](https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/list-events) +- [GET direct_messages/events/show](https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/get-event) +- [POST direct_messages/events/new (message_create)](https://developer.twitter.com/en/docs/direct-messages/sending-and-receiving/api-reference/new-event) +- [POST direct_messages/indicate_typing](https://developer.twitter.com/en/docs/direct-messages/typing-indicator-and-read-receipts/api-reference/new-typing-indicator) +- [POST direct_messages/mark_read](https://developer.twitter.com/en/docs/direct-messages/typing-indicator-and-read-receipts/api-reference/new-read-receipt) + + +- [DELETE direct_messages/welcome_messages/destroy](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/delete-welcome-message) +- [DELETE direct_messages/welcome_messages/rules/destroy](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/delete-welcome-message-rule) +- [PUT direct_messages/welcome_messages/update](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/update-welcome-message) +- [GET direct_messages/welcome_messages/list](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/list-welcome-messages) +- [GET direct_messages/welcome_messages/rules/list](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/list-welcome-message-rules) +- [GET direct_messages/welcome_messages/rules/show](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/get-welcome-message-rule) +- [GET direct_messages/welcome_messages/show](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/get-welcome-message) +- [POST direct_messages/welcome_messages/new](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/new-welcome-message) +- [POST direct_messages/welcome_messages/rules/new](https://developer.twitter.com/en/docs/direct-messages/welcome-messages/api-reference/new-welcome-message-rule) + + +- [GET media/upload (STATUS)](https://developer.twitter.com/en/docs/media/upload-media/api-reference/get-media-upload-status) +- [POST media/subtitles/create](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-subtitles-create) +- [POST media/subtitles/delete](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-subtitles-delete) +- [POST media/upload (APPEND)](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload-append) +- [POST media/upload (FINALIZE)](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload-finalize) +- [POST media/upload (INIT)](https://developer.twitter.com/en/docs/media/upload-media/api-reference/post-media-upload-init) + + +- [GET trends/available](https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-available) +- [GET trends/closest](https://developer.twitter.com/en/docs/trends/locations-with-trending-topics/api-reference/get-trends-closest) +- [GET trends/place](https://developer.twitter.com/en/docs/trends/trends-for-location/api-reference/get-trends-place) + + +- [GET geo/id/:place_id](https://developer.twitter.com/en/docs/geo/place-information/api-reference/get-geo-id-place_id) +- [GET geo/reverse_geocode](https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-reverse_geocode) +- [GET geo/search](https://developer.twitter.com/en/docs/geo/places-near-location/api-reference/get-geo-search) diff --git a/doc/api.md b/doc/api.md index d522767fd..a4ea98577 100644 --- a/doc/api.md +++ b/doc/api.md @@ -1,53 +1,30 @@ -# Friendica API +# Using the APIs * [Home](help) -The Friendica API aims to be compatible with the [GNU Social API](http://wiki.gnusocial.de/gnusocial:api) and the [Twitter API](https://dev.twitter.com/rest/public). +Friendica offers multiple API endpoints to interface with third-party applications: -Please refer to the linked documentation for further information. +- [Twitter](help/API-Twitter) +- [Mastodon](help/API-Mastodon) +- [Friendica-specific](help/API-Friendica) +- [GNU Social](help/API-GNU-Social) -## Implemented API calls +## Usage -### General +### HTTP Method -#### HTTP Method - -API endpoints can restrict the method used to request them. +API endpoints can restrict the HTTP 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. +### Authentication -#### Auth +Friendica supports basic HTTP Auth and OAuth 1 to authenticate the user to the APIs. -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/](/settings/oauth/). -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 +### Errors When an error occurs in API call, an HTTP error code is returned, with an error message Usually: @@ -63,1401 +40,23 @@ Error body is json: ```json - { - "error": "Specific error message", - "request": "API path requested", - "code": "HTTP error code" - } -``` - -xml: - -```xml - - Specific error message - API path requested - HTTP error code - -``` - ---- - -### 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: minimum 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: minimum 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: minimum 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: minimum 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: minimum 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: -HTTP 400 BadRequest - -* on friendica_verbose=true: different JSON returns {"result":"error","message":"xyz"} - ---- - -### externalprofile/show (*) - -#### Parameters - -* profileurl: profile url - ---- - -### favorites (*; AUTH) - -#### Parameters - -* count: Items per page (default: 20) -* page: page number -* since_id: minimum id -* max_id: maximum id -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* user_id -* screen_name - -Favorites aren't displayed to other users, so "user_id" and "screen_name" are unsupported. -Set this values will result in an empty array. - ---- - -### favorites/create (POST,PUT; AUTH) - -#### Parameters - -* id -* include_entities: "true" shows entities for pictures and links (Default: false) - ---- - -### favorites/destroy (POST,DELETE; AUTH) - -#### Parameters - -* id -* include_entities: "true" shows entities for pictures and links (Default: false) - ---- - -### followers/ids (*; AUTH) - -#### Parameters - -* stringify_ids: Send id numbers as text (true) or integers (false)? (default: false) - -#### Unsupported parameters - -* user_id -* screen_name -* cursor - -Friendica doesn't allow showing the followers of other users. - ---- - -### friends/ids (*; AUTH) - -#### Parameters - -* stringify_ids: Send the id numbers as text (true) or integers (false)? (default: false) - -#### Unsupported parameters - -* user_id -* screen_name -* cursor - -Friendica doesn't allow showing the friends of other users. - ---- - -### help/test (*) - ---- - -### lists/ownerships (*; AUTH) - -#### Parameters - -* list_id: ID of the list -* count: Items per page -* page: Page number -* since_id: Minimum ID -* max_id: Maximum ID - -#### Unsupported parameters - -* slug -* owner_screen_name -* owner_id -* include_entities -* include_rts - ---- - -### lists/destroy (POST; AUTH) - -#### Parameters - -* list_id: ID of the list - -#### Unsupported parameters - -* owner_screen_name -* owner_id -* slug - ---- - -### lists/create (POST; AUTH) - -#### Parameters - -* name: name of the list - -#### Unsupported parameters - -* mode -* description - ---- - -### lists/update (POST; AUTH) - -#### Parameters - -* list_id: ID of the list -* name: name of the list - -#### Unsupported parameters - -* slug -* name -* mode -* description -* owner_screen_name -* owner_id - ---- - -### lists/statuses (*; AUTH) - -#### Parameters - -* user_id: ID of the user for whom to return results. - -#### Unsupported parameters - -* screen_name -* count -* cursor - ---- - -### media/upload (POST,PUT; AUTH) - -#### Parameters - -* media: image data - -#### Return values - -Object of: - -* media_id: a media identifier (integer) -* media_id_string: a media identifier (string) -* size: size in byte -* image.w: image width -* image.h: image height -* image.image_type: image mime type -* image.friendica_preview_url: image preview url - ---- - -### media/metadata/create (POST,PUT; AUTH) - -#### Parameters - -Parameters are sent as JSON object: - -``` { - "media_id":"1234", - "alt_text": { - "text":"Here comes the description" - } + "error": "Specific error message", + "request": "API path requested", + "code": "HTTP error code" } ``` -#### Return values - -None - ---- - -### oauth/request_token (*) - -#### Parameters - -* oauth_callback - -#### Unsupported parameters - -* x_auth_access_type - ---- - -### oauth/access_token (*) - -#### Parameters - -* oauth_verifier - -#### Unsupported parameters - -* x_auth_password -* x_auth_username -* x_auth_mode - ---- - -### statuses/destroy (POST,DELETE; AUTH) - -#### Parameters - -* id: message number -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* trim_user - ---- - -### statuses/followers (*; AUTH) - -#### Parameters - -* include_entities: "true" shows entities for pictures and links (Default: false) - ---- - -### statuses/friends (*; AUTH) - -#### Parameters - -* include_entities: "true" shows entities for pictures and links (Default: false) -* count: how many items should be shown (Default: 20) - ---- - -### blocks/list (*; AUTH) - -#### Parameters - -* include_entities: "true" shows entities for pictures and links (Default: false) -* count: Items per page (default: 20). -* page: page number - -#### Unsupported parameters - -* cursor -* skip_status - ---- - -### statuses/friends_timeline (*; AUTH) - -#### Parameters - -* count: Items per page (default: 20) -* page: page number -* since_id: minimum id -* max_id: maximum id -* exclude_replies: don't show replies (default: false) -* conversation_id: Shows all statuses of a given conversation. -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* include_rts -* trim_user -* contributor_details - ---- - -### statuses/home_timeline (*; AUTH) - -#### Parameters - -* count: Items per page (default: 20) -* page: page number -* since_id: minimum id -* max_id: maximum id -* exclude_replies: don't show replies (default: false) -* conversation_id: Shows all statuses of a given conversation. -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* include_rts -* trim_user -* contributor_details - ---- - -### statuses/mentions (*; AUTH) - -#### Parameters - -* count: Items per page (default: 20) -* page: page number -* since_id: minimum id -* max_id: maximum id -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* include_rts -* trim_user -* contributor_details - ---- - -### statuses/public_timeline (*; AUTH) - -#### Parameters - -* count: Items per page (default: 20) -* page: page number -* since_id: minimum id -* max_id: maximum id -* exclude_replies: don't show replies (default: false) -* conversation_id: Shows all statuses of a given conversation. -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* trim_user - ---- - -### statuses/networkpublic_timeline (*; AUTH) - -#### Parameters - -* count: Items per page (default: 20) -* page: page number -* since_id: minimum id -* max_id: maximum id -* include_entities: "true" shows entities for pictures and links (Default: false) - ---- - -### statuses/replies (*; AUTH) - -#### Parameters - -* count: Items per page (default: 20) -* page: page number -* since_id: minimum id -* max_id: maximum id -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* include_rts -* trim_user -* contributor_details - ---- - -### statuses/retweet (POST,PUT; AUTH) - -#### Parameters - -* id: message number -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* trim_user - ---- - -### statuses/show (*; AUTH) - -#### Parameters - -* id: message number -* conversation: if set to "1" show all messages of the conversation with the given id -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* include_my_retweet -* trim_user - ---- - -### statuses/update, statuses/update_with_media - -#### Parameters - -* title: Title of the status -* status: Status in text format -* htmlstatus: Status in HTML format -* in_reply_to_status_id -* lat: latitude -* long: longitude -* media: image data -* source: Application name -* group_allow -* contact_allow -* group_deny -* contact_deny -* network -* include_entities: "true" shows entities for pictures and links (Default: false) -* media_ids: (By now only a single value, no array) - -#### Unsupported parameters - -* trim_user -* place_id -* display_coordinates - ---- - -### statuses/user_timeline (*; AUTH) - -#### Parameters - -* user_id: id of the user -* screen_name: screen name (for technical reasons, this value is not unique!) -* count: Items per page (default: 20) -* page: page number -* since_id: minimum id -* max_id: maximum id -* exclude_replies: don't show replies (default: false) -* conversation_id: Shows all statuses of a given conversation. -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* include_rts -* trim_user -* contributor_details - ---- - -### Return values for statuses/* api calls - -Returned status object is conform to GNU Social/Twitter api. - -Friendica adds some addictional fields: - -- author: a user object, it's the author of the item. In case of a reshare for legacy reasons the "user" field doesn't show the real author. This field always contains the real author of a post. -- owner: a user object, it's the owner of the item. -- private: boolean, true if the item is marked as private -- activities: map with activities related to the item. Every activity is a list of user objects. -- comments: comment numbers - -This properties are prefixed with "friendica_" in JSON responses and namespaced under "http://friendi.ca/schema/api/1/" in XML responses - -JSON: - -```json -[ - { - // ... - 'friendica_author' : { - // user object - }, - 'friendica_owner' : { - // user object - }, - 'friendica_private' : true, - 'friendica_activities': { - 'like': [ - { - // user object - }, - // ... - ], - 'dislike': [], - 'attendyes': [], - 'attendno': [], - 'attendmaybe': [] - }, - 'friendica_comments': 12 - }, - // ... -] -``` - -XML: - -```xml - - - - - true - - - - - - - - - - - - - 21 - - - -``` - - ---- - -### statusnet/config (*) - ---- - -### statusnet/conversation (*; AUTH) - -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: minimum id -* max_id: maximum id -* include_entities: "true" shows entities for pictures and links (Default: false) - ---- - -### statusnet/version (*) - -#### Unsupported parameters - -* user_id -* screen_name -* cursor - -Friendica doesn't allow showing followers of other users. - ---- - -### search (*; AUTH) - -#### Parameters - -* q: search query -* page: the page number (starting at 1) to return -* rpp: the number of statuses to return per page -* count: alias for the rpp parameter -* since_id: returns statuses with ids greater than the given id -* max_id: returns statuses with ids lower or equal to the given id -* exclude_replies: don't show replies (default: false) - -#### Unsupported parameters - -* geocode -* lang -* locale -* result_type -* until -* include_entities - ---- - -### search/tweets (*; AUTH) - -This is an alias for `search`. - ---- - -### saved_searches/list (*; AUTH) - -This call does not have any parameter. - ---- - -### users/search (*) - -#### Parameters - -* q: name of the user - -#### Unsupported parameters - -* page -* count -* include_entities - ---- - -### users/show (*) - -#### Parameters - -* user_id: id of the user -* screen_name: screen name (for technical reasons, this value is not unique!) -* include_entities: "true" shows entities for pictures and links (Default: false) - -#### Unsupported parameters - -* user_id -* screen_name -* cursor - -Friendica doesn't allow showing friends of other users. - ---- - -### users/lookup (*; AUTH) - -#### Parameters - -* user_id: list of ids to lookup - -#### Unsupported parameters - -* screen_name -* include_entities - ---- - -### account/update_profile_image (POST; AUTH) - -#### Parameters - -* image: image data as base64 (Twitter has a limit of 700kb, Friendica allows more) -* profile_id (optional): id of the profile for which the image should be used, default is changing the default profile - -uploads a new profile image (scales 4-6) to database, changes default or specified profile to the new photo - -#### Return values - -On success: - -* JSON return: returns the updated user details (see account/verify_credentials) - -On error: - -* 403 FORBIDDEN: if not authenticated -* 400 BADREQUEST: "no media data submitted", "profile_id not available" -* 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server", - "image size exceeds Friendica Config setting (uploaded size: x)", - "unable to process image data", - "image upload failed" - ---- - -### account/update_profile (POST; AUTH) - -#### Parameters - -* name (optional): full name of the user -* description (optional): a description of the user - -#### Unsupported parameters - -* url -* location -* profile_link_color -* include_entities -* skip_status - ---- - -### friendships/incoming (*; AUTH) - -#### Unsupported parameters - -* cursor -* stringify_ids - -## Implemented API calls (not compatible with other APIs) - ---- - -### friendica/activity/[verb] - -#### parameters - -* id: item id - -Add or remove an activity from an item. -'verb' can be one of: - -* like -* dislike -* attendyes -* attendno -* attendmaybe - -To remove an activity, prepend the verb with "un", eg. "unlike" or "undislike" -Attend verbs disable eachother: that means that if "attendyes" was added to an item, adding "attendno" remove previous "attendyes". -Attend verbs should be used only with event-related items (there is no check at the moment) - -#### Return values - -On success: -json: - -```"ok"``` - -xml: - -```true``` - -On error: -HTTP 400 BadRequest - ---- - -### friendica/group_show (*; AUTH) - -Return all or a specified group of the user with the containing contacts as array. - -#### Parameters - -* gid: optional, if not given, API returns all groups of the user - -#### Return values - -Array of: - -* name: name of the group -* gid: id of the group -* user: array of group members (return from api_get_user() function for each member) - ---- - -### friendica/group_delete (POST,DELETE; AUTH) - -delete the specified group of contacts; API call need to include the correct gid AND name of the group to be deleted. - -#### Parameters - -* gid: id of the group to be deleted -* name: name of the group to be deleted - -#### Return values - -Array of: - -* success: true if successfully deleted -* gid: gid of the deleted group -* name: name of the deleted group -* status: „deleted“ if successfully deleted -* wrong users: empty array - ---- - -### friendica/group_create (POST,PUT; AUTH) - -Create the group with the posted array of contacts as members. - -#### Parameters - -* name: name of the group to be created - -#### POST data - -JSON data as Array like the result of "users/group_show": - -* gid -* name -* array of users - -#### Return values - -Array of: - -* success: true if successfully created or reactivated -* gid: gid of the created group -* name: name of the created group -* status: „missing user“ | „reactivated“ | „ok“ -* wrong users: array of users, which were not available in the contact table - ---- - -### friendica/group_update (POST) - -Update the group with the posted array of contacts as members (post all members of the group to the call; function will remove members not posted). - -#### Parameters - -* gid: id of the group to be changed -* name: name of the group to be changed - -#### POST data - -JSON data as array like the result of „users/group_show“: - -* gid -* name -* array of users - -#### Return values - -Array of: - -* success: true if successfully updated -* gid: gid of the changed group -* name: name of the changed group -* status: „missing user“ | „ok“ -* wrong users: array of users, which were not available in the contact table - ---- - -### friendica/notifications (GET) - -Return last 50 notification for current user, ordered by date with unseen item on top - -#### Parameters - -none - -#### Return values - -Array of: - -* id: id of the note -* type: type of notification as int (see NOTIFY_* constants in boot.php) -* name: full name of the contact subject of the note -* url: contact's profile url -* photo: contact's profile photo -* date: datetime string of the note -* timestamp: timestamp of the node -* date_rel: relative date of the note (eg. "1 hour ago") -* msg: note message in bbcode -* msg_html: note message in html -* msg_plain: note message in plain text -* link: link to note -* seen: seen state: 0 or 1 - ---- - -### friendica/notifications/seen (POST) - -Set note as seen, returns item object if possible - -#### Parameters - -id: id of the note to set seen - -#### Return values - -If the note is linked to an item, the item is returned, just like one of the "statuses/*_timeline" api. - -If the note is not linked to an item, a success status is returned: - -* `success` (json) | `success` (xml) - ---- - -### friendica/photo (*; AUTH) - -#### Parameters - -* photo_id: Resource id of a photo. -* scale: (optional) scale value of the photo - -Returns data of a picture with the given resource. -If 'scale' isn't provided, returned data include full url to each scale of the photo. -If 'scale' is set, returned data include image data base64 encoded. - -possibile scale value are: - -* 0: original or max size by server settings -* 1: image with or height at <= 640 -* 2: image with or height at <= 320 -* 3: thumbnail 160x160 -* 4: Profile image at 300x300 -* 5: Profile image at 80x80 -* 6: Profile image at 48x48 - -An image used as profile image has only scale 4-6, other images only 0-3 - -#### Return values - -json: - -```json - { - "id": "photo id" - "created": "date(YYYY-MM-DD HH:MM:SS)", - "edited": "date(YYYY-MM-DD HH:MM:SS)", - "title": "photo title", - "desc": "photo description", - "album": "album name", - "filename": "original file name", - "type": "mime type", - "height": "number", - "width": "number", - "profile": "1 if is profile photo", - "link": { - "": "url to image" - ... - }, - // if 'scale' is set - "datasize": "size in byte", - "data": "base64 encoded image data" - } -``` - xml: ```xml - - photo id - date(YYYY-MM-DD HH:MM:SS) - date(YYYY-MM-DD HH:MM:SS) - photo title - photo description - album name - original file name - mime type - number - number - 1 if is profile photo - - - ... - - + + Specific error message + API path requested + HTTP error code + ``` ---- - -### friendica/photos/list (*; AUTH) - -Returns a list of all photo resources of the logged in user. - -#### Return values - -json: - -```json - [ - { - id: "resource_id", - album: "album name", - filename: "original file name", - type: "image mime type", - thumb: "url to thumb sized image" - }, - ... - ] -``` - -xml: - -```xml - - - "url to thumb sized image" - - ... - -``` - ---- - -### friendica/photoalbum/delete (POST,DELETE; AUTH) - -#### Parameters - -* album: name of the album to be deleted - -deletes all images with the specified album name, is not reversible -> ensure that client is asking user for being sure to do this - -#### Return values - -On success: - -* JSON return {"result":"deleted","message":"album 'xyz' with all containing photos has been deleted."} - -On error: - -* 403 FORBIDDEN: if not authenticated -* 400 BADREQUEST: "no albumname specified", "album not available" -* 500 INTERNALSERVERERROR: "problem with deleting item occured", "unknown error - deleting from database failed" - ---- - -### friendica/photoalbum/update (POST,PUT; AUTH) - -#### Parameters - -* album: name of the album to be updated -* album_new: new name of the album - -changes the album name to album_new for all photos in album - -#### Return values - -On success: - -* JSON return {"result":"updated","message":"album 'abc' with all containing photos has been renamed to 'xyz'."} - -On error: - -* 403 FORBIDDEN: if not authenticated -* 400 BADREQUEST: "no albumname specified", "no new albumname specified", "album not available" -* 500 INTERNALSERVERERROR: "unknown error - updating in database failed" - ---- - -### friendica/photo/create (POST; AUTH) - -### friendica/photo/update (POST; AUTH) - -#### Parameters - -* photo_id (optional): if specified the photo with this id will be updated -* media (optional): image data as base64, only optional if photo_id is specified (new upload must have media) -* desc (optional): description for the photo, updated when photo_id is specified -* album: name of the album to be deleted (always necessary) -* album_new (optional): can be used to change the album of a single photo if photo_id is specified -* allow_cid/allow_gid/deny_cid/deny_gid (optional): on create: empty string or omitting = public photo, specify in format '``````' for private photo; - on update: keys need to be present with empty values for changing a private photo to public - -both calls point to one function for creating AND updating photos. -Saves data for the scales 0-2 to database (see above for scale description). -Call adds non-visible entries to items table to enable authenticated contacts to comment/like the photo. -Client should pay attention to the fact that updated access rights are not transferred to the contacts. i.e. public photos remain publicly visible if they have been commented/liked before setting visibility back to a limited group. -Currently it is best to inform user that updating rights is not the right way to do this, and offer a solution to add photo as a new photo with the new rights instead. - -#### Return values - -On success: - -* new photo uploaded: JSON return with photo data (see friendica/photo) -* photo updated - changed photo data: JSON return with photo data (see friendica/photo) -* photo updated - changed info: JSON return {"result":"updated","message":"Image id 'xyz' has been updated."} -* photo updated - nothing changed: JSON return {"result":"cancelled","message":"Nothing to update for image id 'xyz'."} - -On error: - -* 403 FORBIDDEN: if not authenticated -* 400 BADREQUEST: "no albumname specified", "no media data submitted", "photo not available", "acl data invalid" -* 500 INTERNALSERVERERROR: "image size exceeds PHP config settings, file was rejected by server", - "image size exceeds Friendica Config setting (uploaded size: x)", - "unable to process image data", - "image upload failed", - "unknown error - uploading photo failed, see Friendica log for more information", - "unknown error - update photo entry in database failed", - "unknown error - this error on uploading or updating a photo should never happen" - ---- - -### friendica/photo/delete (DELETE; AUTH) - -#### Parameters - -* photo_id: id of the photo to be deleted - -deletes a single image with the specified id, is not reversible -> ensure that client is asking user for being sure to do this -Sets item table entries for this photo to deleted = 1 - -#### Return values - -On success: - -* JSON return {"result":"deleted","message":"photo with id 'xyz' has been deleted from server."} - -On error: - -* 403 FORBIDDEN: if not authenticated -* 400 BADREQUEST: "no photo_id specified", "photo not available" -* 500 INTERNALSERVERERROR: "unknown error on deleting photo", "problem with deleting items occurred" - ---- - -### friendica/direct_messages_setseen (GET; AUTH) - -#### Parameters - -* id: id of the message to be updated as seen - -#### Return values - -On success: - -* JSON return {"result":"ok","message":"message set to seen"} - -On error: - -* different JSON returns {"result":"error","message":"xyz"} - ---- - -### friendica/direct_messages_search (GET; AUTH) - -#### Parameters - -* searchstring: string for which the API call should search as '%searchstring%' in field 'body' of all messages of the authenticated user (caption ignored) - -#### Return values - -Returns only tested with JSON, XML might work as well. - -On success: - -* JSON return {"success":"true","search_results": array of found messages} -* JSOn return {"success":"false","search_results":"nothing found"} - -On error: - -* different JSON returns {"result":"error","message":"searchstring not specified"} - ---- - -### friendica/profile/show (GET; AUTH) - -show data of all profiles or a single profile of the authenticated user - -#### Parameters - -* profile_id: id of the profile to be returned (optional, if omitted all profiles are returned by default) - -#### Return values - -On success: Array of: - -* multi_profiles: true if user has activated multi_profiles -* global_dir: URL of the global directory set in server settings -* friendica_owner: user data of the authenticated user -* profiles: array of the profile data - -On error: -HTTP 403 Forbidden: when no authentication was provided -HTTP 400 Bad Request: if given profile_id is not in the database or is not assigned to the authenticated user - -General description of profile data in API returns: - -* profile_id -* profile_name -* is_default: true if this is the public profile -* hide_friends: true if friends are hidden -* profile_photo -* profile_thumb -* publish: true if published on the server's local directory -* net_publish: true if published to global_dir -* description ... homepage: different data fields from 'profile' table in database -* users: array with the users allowed to view this profile (empty if is_default=true) - ---- - -## Not Implemented API calls - -The following API calls are implemented in GNU Social but not in Friendica: (incomplete) - -* statuses/retweets_of_me -* friendships/create -* friendships/destroy -* friendships/exists -* friendships/show -* account/update_profile_background_image -* blocks/create -* blocks/destroy - -The following API calls from the Twitter API are not implemented in either Friendica or GNU Social: - -* statuses/mentions_timeline -* statuses/retweets/:id -* statuses/oembed -* statuses/retweeters/ids -* statuses/lookup -* direct_messages/show -* friendships/no_retweets/ids -* friendships/outgoing -* friendships/update -* friends/list -* friendships/lookup -* account/settings -* account/update_delivery_device -* blocks/ids -* users/show -* users/search -* account/remove_profile_banner -* account/update_profile_banner -* users/profile_banner -* mutes/users/create -* mutes/users/destroy -* mutes/users/ids -* mutes/users/list -* users/suggestions/:slug -* users/suggestions -* users/suggestions/:slug/members -* favorites/list -* lists/list -* lists/members/destroy -* lists/memberships -* lists/subscribers -* lists/subscribers/create -* lists/subscribers/show -* lists/subscribers/destroy -* lists/members/create_all -* lists/members/show -* lists/members -* lists/members/create -* lists/show -* lists/subscriptions -* lists/members/destroy_all -* saved_searches/show/:id -* saved_searches/create -* saved_searches/destroy/:id -* geo/id/:place_id -* geo/reverse_geocode -* geo/search -* geo/place -* trends/place -* trends/available -* help/configuration -* help/languages -* help/privacy -* help/tos -* trends/closest -* users/report_spam - ---- - ---- - ## Usage Examples ### BASH / cURL From 9e41488c40737d0615908c49f82157d851d5d22d Mon Sep 17 00:00:00 2001 From: Hypolite Petovan Date: Tue, 10 Dec 2019 07:54:11 -0500 Subject: [PATCH 7/7] Fix JSON syntax in Friendica API doc --- doc/API-Friendica.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/API-Friendica.md b/doc/API-Friendica.md index 2e33a887d..76440600c 100644 --- a/doc/API-Friendica.md +++ b/doc/API-Friendica.md @@ -435,7 +435,7 @@ json: ```json { - "id": "photo id" + "id": "photo id", "created": "date(YYYY-MM-DD HH:MM:SS)", "edited": "date(YYYY-MM-DD HH:MM:SS)", "title": "photo title", @@ -447,7 +447,7 @@ json: "width": "number", "profile": "1 if is profile photo", "link": { - "": "url to image" + "": "url to image", ... }, // if 'scale' is set @@ -489,11 +489,11 @@ json: ```json [ { - id: "resource_id", - album: "album name", - filename: "original file name", - type: "image mime type", - thumb: "url to thumb sized image" + "id": "resource_id", + "album": "album name", + "filename": "original file name", + "type": "image mime type", + "thumb": "url to thumb sized image" }, ... ]