includes/functions-api.php

   1 <?php
   2 /*
   3  * YOURLS
   4  * Functions for the API
   5  *
   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
   8  *
   9  */
  10
  11 /**
  12  * API function wrapper: Shorten a URL
  13  *
  14  * @since 1.6
  15  * @return array Result of API call
  16  */
  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 );
  25 }
  26
  27 /**
  28  * API function wrapper: Stats about links (XX top, bottom, last, rand)
  29  *
  30  * @since 1.6
  31  * @return array Result of API call
  32  */
  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 ) );
  38 }
  39
  40 /**
  41  * API function wrapper: Just the global counts of shorturls and clicks
  42  *
  43  * @since 1.6
  44  * @return array Result of API call
  45  */
  46 function yourls_api_action_db_stats() {
  47         return yourls_apply_filter( 'api_result_db_stats', yourls_api_db_stats() );
  48 }
  49
  50 /**
  51  * API function wrapper: Stats for a shorturl
  52  *
  53  * @since 1.6
  54  * @return array Result of API call
  55  */
  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 ) );
  59 }
  60
  61 /**
  62  * API function wrapper: Expand a short link
  63  *
  64  * @since 1.6
  65  * @return array Result of API call
  66  */
  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 ) );
  70 }
  71
  72 /**
  73  * API function wrapper: return version numbers
  74  *
  75  * @since 1.6
  76  * @return array Result of API call
  77  */
  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 );
  83 }
  84
  85 /**
  86  * Output and return API result
  87  *
  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'
  90  *
  91  * Most likely, script should not do anything after outputting this
  92  *
  93  * @since 1.6
  94  *
  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
 100  */
 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'] );
 105         }
 106
 107         yourls_do_action( 'pre_api_output', $mode, $output, $send_headers, $echo );
 108
 109     if( $send_headers ) {
 110         if( isset( $output['statusCode'] ) ) {
 111             $code = $output['statusCode'];
 112         } elseif ( isset( $output['errorCode'] ) ) {
 113             $code = $output['errorCode'];
 114         } else {
 115             $code = 200;
 116         }
 117         yourls_status_header( $code );
 118     }
 119
 120     $result = '';
 121
 122         switch ( $mode ) {
 123                 case 'plain':
 124             if( $send_headers )
 125                 yourls_content_type_header( 'text/plain' );
 126                         $result = sprintf(
 127                                 "STATUS: %s\r\nCODE: %s\r\nURL: %s\r\nTITLE: %s\r\nSHORT: %s\r\nMESSAGE: %s\r\n",
 128                                 $output["status"], $output["statusCode"],
 129                                 $output["url"]["url"], yourls_trim_long_string($output["title"]),
 130                                 $output["shorturl"], $output["message"]
 131                         );
 132                         break;
 133
 134                 case 'jsonp':
 135             if( $send_headers )
 136                 yourls_content_type_header( 'application/javascript' );
 137
 138             $callback = isset( $output['callback'] ) ? $output['callback'] : '';
 139                         $result =  $callback . '(' . json_encode( $output ) . ')';
 140                         break;
 141
 142                 case 'json':
 143             if( $send_headers )
 144                 yourls_content_type_header( 'application/json' );
 145
 146                         $result = json_encode( $output );
 147                         break;
 148
 149                 case 'xml':
 150             if( $send_headers )
 151                 yourls_content_type_header( 'application/xml' );
 152
 153                         $result = yourls_xml_encode( $output );
 154                         break;
 155
 156                 case 'simple':
 157                 default:
 158             if( $send_headers )
 159                 yourls_content_type_header( 'text/plain' );
 160
 161                         $result = isset( $simple ) ? $simple : '';
 162                         break;
 163         }
 164
 165     if( $echo ) {
 166         echo $result;
 167     }
 168
 169         yourls_do_action( 'api_output', $mode, $output, $send_headers, $echo );
 170
 171     return $result;
 172 }
 173
 174 /**
 175  * Return array for API stat requests
 176  *
 177  */
 178 function yourls_api_stats( $filter = 'top', $limit = 10, $start = 0 ) {
 179         $return = yourls_get_stats( $filter, $limit, $start );
 180         $return['simple']  = 'Need either XML or JSON format for stats';
 181         $return['message'] = 'success';
 182         return yourls_apply_filter( 'api_stats', $return, $filter, $limit, $start );
 183 }
 184
 185 /**
 186  * Return array for counts of shorturls and clicks
 187  *
 188  */
 189 function yourls_api_db_stats() {
 190         $return = array(
 191                 'db-stats'   => yourls_get_db_stats(),
 192                 'statusCode' => 200,
 193                 'simple'     => 'Need either XML or JSON format for stats',
 194                 'message'    => 'success',
 195         );
 196
 197         return yourls_apply_filter( 'api_db_stats', $return );
 198 }
 199
 200 /**
 201  * Return array for API stat requests
 202  *
 203  */
 204 function yourls_api_url_stats( $shorturl ) {
 205         $keyword = str_replace( YOURLS_SITE . '/' , '', $shorturl ); // accept either 'http://ozh.in/abc' or 'abc'
 206         $keyword = yourls_sanitize_string( $keyword );
 207
 208         $return = yourls_get_link_stats( $keyword );
 209         $return['simple']  = 'Need either XML or JSON format for stats';
 210         return yourls_apply_filter( 'api_url_stats', $return, $shorturl );
 211 }
 212
 213 /**
 214  * Expand short url to long url
 215  *
 216  */
 217 function yourls_api_expand( $shorturl ) {
 218         $keyword = str_replace( YOURLS_SITE . '/' , '', $shorturl ); // accept either 'http://ozh.in/abc' or 'abc'
 219         $keyword = yourls_sanitize_string( $keyword );
 220
 221         $longurl = yourls_get_keyword_longurl( $keyword );
 222
 223         if( $longurl ) {
 224                 $return = array(
 225                         'keyword'   => $keyword,
 226                         'shorturl'  => YOURLS_SITE . "/$keyword",
 227                         'longurl'   => $longurl,
 228             'title'     => yourls_get_keyword_title( $keyword ),
 229                         'simple'    => $longurl,
 230                         'message'   => 'success',
 231                         'statusCode' => 200,
 232                 );
 233         } else {
 234                 $return = array(
 235                         'keyword'   => $keyword,
 236                         'simple'    => 'not found',
 237                         'message'   => 'Error: short URL not found',
 238                         'errorCode' => 404,
 239                 );
 240         }
 241
 242         return yourls_apply_filter( 'api_expand', $return, $shorturl );
 243 }