includes/api/ApiRsd.php

   1 <?php
   2
   3 /**
   4  * API for MediaWiki 1.17+
   5  *
   6  * Copyright © 2010 Bryan Tong Minh and Brooke Vibber
   7  *
   8  * This program is free software; you can redistribute it and/or modify
   9  * it under the terms of the GNU General Public License as published by
  10  * the Free Software Foundation; either version 2 of the License, or
  11  * (at your option) any later version.
  12  *
  13  * This program is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16  * GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License along
  19  * with this program; if not, write to the Free Software Foundation, Inc.,
  20  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  21  * http://www.gnu.org/copyleft/gpl.html
  22  *
  23  * @file
  24  */
  25
  26 namespace MediaWiki\Api;
  27
  28 use MediaWiki\MediaWikiServices;
  29 use MediaWiki\Title\Title;
  30
  31 /**
  32  * API module for sending out RSD information
  33  * @ingroup API
  34  */
  35 class ApiRsd extends ApiBase {
  36         public function execute() {
  37                 $result = $this->getResult();
  38
  39                 $result->addValue( null, 'version', '1.0' );
  40                 $result->addValue( null, 'xmlns', 'http://archipelago.phrasewise.com/rsd' );
  41
  42                 $service = [
  43                         'apis' => $this->formatRsdApiList(),
  44                         'engineName' => 'MediaWiki',
  45                         'engineLink' => 'https://www.mediawiki.org/',
  46                         'homePageLink' => Title::newMainPage()->getCanonicalURL(),
  47                 ];
  48
  49                 ApiResult::setSubelementsList( $service, [ 'engineName', 'engineLink', 'homePageLink' ] );
  50                 ApiResult::setIndexedTagName( $service['apis'], 'api' );
  51
  52                 $result->addValue( null, 'service', $service );
  53         }
  54
  55         public function getCustomPrinter() {
  56                 return new ApiFormatXmlRsd( $this->getMain(), 'xml' );
  57         }
  58
  59         protected function getExamplesMessages() {
  60                 return [
  61                         'action=rsd'
  62                                 => 'apihelp-rsd-example-simple',
  63                 ];
  64         }
  65
  66         public function isReadMode() {
  67                 return false;
  68         }
  69
  70         /**
  71          * Builds an internal list of APIs to expose information about.
  72          * Normally this only lists the MediaWiki API, with its base URL,
  73          * link to documentation, and a marker as to available authentication
  74          * (to aid in OAuth client apps switching to support in the future).
  75          *
  76          * Extensions can expose other APIs, such as WordPress or Twitter-
  77          * compatible APIs, by hooking 'ApiRsdServiceApis' and adding more
  78          * elements to the array.
  79          *
  80          * See https://cyber.harvard.edu/blogs/gems/tech/rsd.html for
  81          * the base RSD spec, and check WordPress and StatusNet sites for
  82          * in-production examples listing several blogging and micrblogging
  83          * APIs.
  84          *
  85          * @return array[]
  86          */
  87         protected function getRsdApiList() {
  88                 // Loaded here rather than injected due to the direct extension of ApiBase.
  89                 $urlUtils = MediaWikiServices::getInstance()->getUrlUtils();
  90                 $apis = [
  91                         'MediaWiki' => [
  92                                 // The API link is required for all RSD API entries.
  93                                 'apiLink' => (string)$urlUtils->expand( wfScript( 'api' ), PROTO_CURRENT ),
  94
  95                                 // Docs link is optional, but recommended.
  96                                 'docs' => 'https://www.mediawiki.org/wiki/Special:MyLanguage/API',
  97
  98                                 // Some APIs may need a blog ID, but it may be left blank.
  99                                 'blogID' => '',
 100
 101                                 // Additional settings are optional.
 102                                 'settings' => [
 103                                         // Change this to true in the future as an aid to
 104                                         // machine discovery of OAuth for API access.
 105                                         'OAuth' => false,
 106                                 ]
 107                         ],
 108                 ];
 109                 $this->getHookRunner()->onApiRsdServiceApis( $apis );
 110
 111                 return $apis;
 112         }
 113
 114         /**
 115          * Formats the internal list of exposed APIs into an array suitable
 116          * to pass to the API's XML formatter.
 117          *
 118          * @return array
 119          */
 120         protected function formatRsdApiList() {
 121                 $apis = $this->getRsdApiList();
 122
 123                 $outputData = [];
 124                 foreach ( $apis as $name => $info ) {
 125                         $data = [
 126                                 'name' => $name,
 127                                 'preferred' => wfBoolToStr( $name == 'MediaWiki' ),
 128                                 'apiLink' => $info['apiLink'],
 129                                 'blogID' => $info['blogID'] ?? '',
 130                         ];
 131                         $settings = [];
 132                         if ( isset( $info['docs'] ) ) {
 133                                 $settings['docs'] = $info['docs'];
 134                                 ApiResult::setSubelementsList( $settings, 'docs' );
 135                         }
 136                         if ( isset( $info['settings'] ) ) {
 137                                 foreach ( $info['settings'] as $setting => $val ) {
 138                                         if ( is_bool( $val ) ) {
 139                                                 $xmlVal = wfBoolToStr( $val );
 140                                         } else {
 141                                                 $xmlVal = $val;
 142                                         }
 143                                         $setting = [ 'name' => $setting ];
 144                                         ApiResult::setContentValue( $setting, 'value', $xmlVal );
 145                                         $settings[] = $setting;
 146                                 }
 147                         }
 148                         if ( count( $settings ) ) {
 149                                 ApiResult::setIndexedTagName( $settings, 'setting' );
 150                                 $data['settings'] = $settings;
 151                         }
 152                         $outputData[] = $data;
 153                 }
 154
 155                 return $outputData;
 156         }
 157
 158         public function getHelpUrls() {
 159                 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Rsd';
 160         }
 161 }
 162
 163 /** @deprecated class alias since 1.43 */
 164 class_alias( ApiRsd::class, 'ApiRsd' );