extra/mediawiki/api/api-docs.factor

   1 USING: help.markup help.syntax mediawiki.api ;
   2 IN: mediawiki.api
   3
   4 ARTICLE: "mediawiki.api" "MediaWiki API"
   5 { $url "https://www.mediawiki.org/wiki/API:Main_page" }
   6 { $heading "Configuration" }
   7 "Set " { $snippet "endpoint" } " to the API entry point. An"
   8 "example for Wikimedia wikis:"
   9 { $code
  10 "USING: formatting mediawiki.api namespaces ;"
  11 ": wikimedia-url ( lang family -- str )"
  12 "    \"https://%s.%s.org/w/api.php\" sprintf ;"
  13 "\"en\" \"wikipedia\" wikimedia-url endpoint set-global" }
  14 $nl
  15 "For Wikimedia wikis, also provide contact information in " {
  16 $snippet "contact" } " so that wiki operators can contact you in"
  17 "case of malfunction, including username or email, and possibly"
  18 "the task name:"
  19 { $code
  20 "USING: mediawiki.api namespaces ;"
  21 "\"BotName/Task1 (email@address.tld)\" contact set-global" }
  22 $nl
  23 "OAuth login with an owner-only consumer:"
  24 { $code
  25 "USING: mediawiki.api namespaces ;"
  26 "\"consumer-token\""
  27 "\"consumer-secret\""
  28 "\"access-token\""
  29 "\"access-secret\""
  30 "<oauth-login> oauth-login set-global" }
  31 $nl
  32 "Login with username and password:"
  33 { $code
  34 "USING: mediawiki.api namespaces ;"
  35 "\"username\""
  36 "\"password\""
  37 "<password-login> password-login set-global" }
  38 $nl
  39 "If both login methods are given, OAuth is preferred. If none"
  40 "are given, you're not logged in."
  41 $nl
  42 "If you use several wikis simultaneously, you might want to save"
  43 "your " { $snippet "cookies" } " (if you use the password login"
  44 "method) and your " { $snippet "csrf-token" } ". You also should"
  45 "invalidate your csrf-token before using an action that requires"
  46 "a csrf token in a wiki for the first time:"
  47 { $code
  48 "USING: mediawiki.api namespaces ;"
  49 "f csrf-token set-global" }
  50
  51 { $heading "Usage" }
  52 "Main entry point:"
  53 { $subsections api-call }
  54 "Query the API:"
  55 { $subsections query page-content }
  56 "Actions that require a csrf token:"
  57 { $subsections token-call edit-page move-page email }
  58 "Sometimes you need to loop over a non-query API call:"
  59 { $subsection call-continue } ;
  60
  61 HELP: api-call
  62 { $values
  63     { "params" "an assoc of API parameters" }
  64     { "assoc" "a parsed JSON result" } }
  65 { $description
  66 "Makes a call to a MediaWiki API. Retries on certain error"
  67 "conditions. Uses a maxlag value of 5 and, in the case of"
  68 "replication lag, pauses for the amount of time specified by the"
  69 "API. Pauses 10 minutes on non-200 status codes and 5 minutes"
  70 "when the database is set to readonly. Prints debug information"
  71 "on non-200 status codes and JSON parse failure. Prints API"
  72 "warnings and errors." }
  73 { $examples
  74 { $code
  75 "USING: locals mediawiki.api ;"
  76 "{"
  77 "    { \"meta\" \"tokens\" }"
  78 "    { \"type\" \"watch\" }"
  79 "} query \"watchtoken\" of"
  80 "[| token | {"
  81 "    { \"action\" \"watch\" }"
  82 "    { \"titles\" {"
  83 "       \"Volkswagen Beetle\""
  84 "       \"Factor (programming language)\""
  85 "   } }"
  86 "    { \"token\" token }"
  87 "} api-call ] call drop" } } ;
  88
  89 HELP: query
  90 { $values
  91     { "params" "an assoc of query parameters" }
  92     { "seq" "a stripped parsed JSON result" } }
  93 { $description
  94 "Makes an API query and extracts the query result from the"
  95 "JSON."
  96 $nl
  97 "The following two code snippets are equivalent:"
  98 { $code
  99 "{"
 100 "     { \"action\" \"query\" }"
 101 "     { \"meta\" \"userinfo\" }"
 102 "} api-call"
 103 "\"query\" \"userinfo\" \"name\" [ of ] tri@" }
 104 { $code " { { \"meta\" \"userinfo\" } } query \"name\" of" }
 105 $nl
 106 "The following two code snippets are also equivalent:"
 107 { $code
 108 "{"
 109 "    { \"action\" \"query\" }"
 110 "    { \"list\" \"watchlistraw\" }"
 111 "} api-call"
 112 "\"watchlistraw\" of" }
 113 { $code " { { \"list\" \"watchlistraw\" } } query" } } ;
 114
 115 HELP: page-content
 116 { $values
 117     { "title" "a page title" }
 118     { "content" "a page content" } }
 119 { $description
 120 "Gets the page content of the most current revision." } ;
 121
 122 HELP: token-call
 123 { $values
 124     { "params" "an assoc of API call parameters" }
 125     { "assoc" "a parsed JSON result" } }
 126 { $description
 127 "Constructs API call with csrf token, fetches token if necessary." }
 128 { $notes "This word is used in the implementation of "
 129 { $links edit-page move-page } " and " { $link email } "." } ;
 130
 131 HELP: edit-page
 132 { $values
 133     { "title" "a page title" }
 134     { "text" "a page content" }
 135     { "summary" "an edit summary" }
 136     { "params" "an assoc of additional parameters (section,
 137     minor)" }
 138     { "assoc" "a parsed JSON result" } }
 139 { $description
 140 "Changes the content of a page. In conjunction with "
 141 { $link page-content } ", it uses the revision timstamp and the"
 142 "timestamp of when you begin editing for edit-conflict"
 143 "detection."
 144 $nl
 145 "You can disable the bot flag by setting " { $snippet "botflag" }
 146 " to " { $link f } ":"
 147 { $code "f botflag set-global" } } ;
 148
 149 HELP: move-page
 150 { $values
 151     { "from" "a page source" }
 152     { "to" "a page destination" }
 153     { "reason" "a summary" }
 154     { "params" "an assoc of additional parameters" }
 155     { "assoc" "a parsed JSON result" } }
 156 { $description
 157 "Moves " { $snippet "from" } " to " { $snippet "to" } ". Also moves"
 158 "talk pages." } ;
 159
 160 HELP: email
 161 { $values
 162     { "target" "a username" }
 163     { "subject" "a subject line" }
 164     { "text" "a message body" }
 165     { "assoc" "a parsed JSON result" } }
 166 { $description "Sends an email to " { $snippet "target" } "." } ;
 167
 168 HELP: call-continue
 169 { $values
 170     { "params" "an assoc of API call parameters" }
 171     { "quot1" { $quotation ( params -- obj assoc ) } }
 172     { "quot2" { $quotation ( ... -- ... ) } }
 173     { "seq" { "a sequence" } } }
 174 { $description "Calls the API until all input is consumed." }
 175 { $notes "This word is used in the implementation of "
 176 { $link query } "." }
 177 { $examples
 178 { $code
 179 "USING: mediawiki.api assocs kernel ;"
 180 "{"
 181 "    { \"meta\" \"tokens\" }"
 182 "    { \"type\" \"watch\" }"
 183 "} query \"watchtoken\" of "
 184 "\"Category:Concatenative programming languages\""
 185 "\"Category:Stack-oriented programming languages\""
 186 "[| token cat | {"
 187 "    { \"action\" \"watch\" }"
 188 "    { \"generator\" \"categorymembers\" }"
 189 "    { \"gcmtitle\" cat }"
 190 "    { \"gcmnamespace\" 0 }"
 191 "    { \"gcmtype\" \"page\" }"
 192 "    { \"gcmlimit\" 50 }"
 193 "    { \"token\" token }"
 194 "} [ api-call dup ] [ ] call-continue drop ] bi-curry@ bi" } } ;
 195
 196 ABOUT: "mediawiki.api"