4 * Functions for the API
6 * Note about translation : this file should NOT be translation ready
7 * API messages and returns are supposed to be programmatically tested, so default English is expected
12 * API function wrapper: Shorten a URL
15 * @return array Result of API call
17 function yourls_api_action_shorturl() {
18 $url = ( isset( $_REQUEST['url'] ) ? $_REQUEST['url'] : '' );
19 $keyword = ( isset( $_REQUEST['keyword'] ) ? $_REQUEST['keyword'] : '' );
20 $title = ( isset( $_REQUEST['title'] ) ? $_REQUEST['title'] : '' );
21 $return = yourls_add_new_link( $url, $keyword, $title );
22 $return['simple'] = ( isset( $return['shorturl'] ) ? $return['shorturl'] : '' ); // This one will be used in case output mode is 'simple'
23 unset( $return['html'] ); // in API mode, no need for our internal HTML output
24 return yourls_apply_filter( 'api_result_shorturl', $return );
28 * API function wrapper: Stats about links (XX top, bottom, last, rand)
31 * @return array Result of API call
33 function yourls_api_action_stats() {
34 $filter = ( isset( $_REQUEST['filter'] ) ? $_REQUEST['filter'] : '' );
35 $limit = ( isset( $_REQUEST['limit'] ) ? $_REQUEST['limit'] : '' );
36 $start = ( isset( $_REQUEST['start'] ) ? $_REQUEST['start'] : '' );
37 return yourls_apply_filter( 'api_result_stats', yourls_api_stats( $filter, $limit, $start ) );
41 * API function wrapper: Just the global counts of shorturls and clicks
44 * @return array Result of API call
46 function yourls_api_action_db_stats() {
47 return yourls_apply_filter( 'api_result_db_stats', yourls_api_db_stats() );
51 * API function wrapper: Stats for a shorturl
54 * @return array Result of API call
56 function yourls_api_action_url_stats() {
57 $shorturl = ( isset( $_REQUEST['shorturl'] ) ? $_REQUEST['shorturl'] : '' );
58 return yourls_apply_filter( 'api_result_url_stats', yourls_api_url_stats( $shorturl ) );
62 * API function wrapper: Expand a short link
65 * @return array Result of API call
67 function yourls_api_action_expand() {
68 $shorturl = ( isset( $_REQUEST['shorturl'] ) ? $_REQUEST['shorturl'] : '' );
69 return yourls_apply_filter( 'api_result_expand', yourls_api_expand( $shorturl ) );
73 * API function wrapper: return version numbers
76 * @return array Result of API call
78 function yourls_api_action_version() {
79 $return['version'] = $return['simple'] = YOURLS_VERSION;
80 if( isset( $_REQUEST['db'] ) && $_REQUEST['db'] == 1 )
81 $return['db_version'] = YOURLS_DB_VERSION;
82 return yourls_apply_filter( 'api_result_version', $return );
86 * Output and return API result
88 * This function will echo (or only return if asked) an array as JSON, JSONP or XML. If the array has a
89 * 'simple' key, it can also output that key as unformatted text if expected output mode is 'simple'
91 * Most likely, script should not do anything after outputting this
95 * @param string $mode Expected output mode ('json', 'jsonp', 'xml', 'simple')
96 * @param array $output Array of things to output
97 * @param bool $send_headers Optional, default true: Whether a headers (status, content type) should be sent or not
98 * @param bool $echo Optional, default true: Whether the output should be outputted or just returned
99 * @return string API output, as an XML / JSON / JSONP / raw text string
101 function yourls_api_output( $mode, $output, $send_headers = true, $echo = true ) {
102 if( isset( $output['simple'] ) ) {
103 $simple = $output['simple'];
104 unset( $output['simple'] );
107 yourls_do_action( 'pre_api_output', $mode, $output, $send_headers, $echo );
109 if( $send_headers ) {
110 if( isset( $output['statusCode'] ) ) {
111 $code = $output['statusCode'];
112 } elseif ( isset( $output['errorCode'] ) ) {
113 $code = $output['errorCode'];
117 yourls_status_header( $code );
125 yourls_content_type_header( 'application/javascript' );
127 $callback = isset( $output['callback'] ) ? $output['callback'] : '';
128 $result = $callback . '(' . json_encode( $output ) . ')';
133 yourls_content_type_header( 'application/json' );
135 $result = json_encode( $output );
140 yourls_content_type_header( 'application/xml' );
142 $result = yourls_xml_encode( $output );
148 yourls_content_type_header( 'text/plain' );
150 $result = isset( $simple ) ? $simple : '';
158 yourls_do_action( 'api_output', $mode, $output, $send_headers, $echo );
164 * Return array for API stat requests
167 function yourls_api_stats( $filter = 'top', $limit = 10, $start = 0 ) {
168 $return = yourls_get_stats( $filter, $limit, $start );
169 $return['simple'] = 'Need either XML or JSON format for stats';
170 $return['message'] = 'success';
171 return yourls_apply_filter( 'api_stats', $return, $filter, $limit, $start );
175 * Return array for counts of shorturls and clicks
178 function yourls_api_db_stats() {
180 'db-stats' => yourls_get_db_stats(),
182 'simple' => 'Need either XML or JSON format for stats',
183 'message' => 'success',
186 return yourls_apply_filter( 'api_db_stats', $return );
190 * Return array for API stat requests
193 function yourls_api_url_stats( $shorturl ) {
194 $keyword = str_replace( YOURLS_SITE . '/' , '', $shorturl ); // accept either 'http://ozh.in/abc' or 'abc'
195 $keyword = yourls_sanitize_string( $keyword );
197 $return = yourls_get_link_stats( $keyword );
198 $return['simple'] = 'Need either XML or JSON format for stats';
199 return yourls_apply_filter( 'api_url_stats', $return, $shorturl );
203 * Expand short url to long url
206 function yourls_api_expand( $shorturl ) {
207 $keyword = str_replace( YOURLS_SITE . '/' , '', $shorturl ); // accept either 'http://ozh.in/abc' or 'abc'
208 $keyword = yourls_sanitize_string( $keyword );
210 $longurl = yourls_get_keyword_longurl( $keyword );
214 'keyword' => $keyword,
215 'shorturl' => YOURLS_SITE . "/$keyword",
216 'longurl' => $longurl,
217 'title' => yourls_get_keyword_title( $keyword ),
218 'simple' => $longurl,
219 'message' => 'success',
224 'keyword' => $keyword,
225 'simple' => 'not found',
226 'message' => 'Error: short URL not found',
231 return yourls_apply_filter( 'api_expand', $return, $shorturl );