The Kuma API

  • Revision slug: Project:The_Kuma_API
  • Revision title: The Kuma API
  • Revision id: 355127
  • Created:
  • Creator: lmorchard
  • Is current revision? No
  • Comment

Revision Content

Introduction

MDN / Kuma doesn't have a central API. Instead, our general approach is to offer ways to turn human-accessible resources into machine-friendly data.

Cross-Origin Resource Sharing

Our intent is to enable CORS on all public data where it's safe to do so - which should include pretty much everything. If you find something that cannot be used with cross-origin requests, that's a bug to be fixed!

Feeds (RSS & JSON)

Check out the Project:Feeds page, if you're interested in accessing various read-only feeds of data. These include changes to documents, documents by tag, and more. Feel free to file a bug if there's some collection of data you'd like from MDN that we don't yet offer!

Or, better yet: Fork us on GitHub and submit a pull request!

Document parameters

We also support several useful query parameter options on every Kuma wiki document URL, when fetched via HTTP GET or viewed in a browser:

Parameter Description
?raw

Instructs Kuma to return the raw content of the page, without any of the skin material, such as the headers, footers, and so forth. This does not execute templates or scripts.

For example: https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw

&macros

Instructs Kuma to execute all the templates in the page.

For example: https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw&macros

&include

Tells Kuma to strip out any blocks that have the class "noinclude" on them. This is useful to get the output as it would appear when included in another page, rather than as a standalone page. Often this will remove sample code and the like (although not always).

For example: https://developer.mozilla.org/en-US/docs/XUL/Attribute/align?raw&macros&include

&section=[section-id]

Instructs Kuma to return the content from only the section with the specified anchor name.

For example: https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw&section=Semantics

Document metadata resources

Along with parameters to tweak the response of a document URL, there are also some alternate views on documents:

$toc

Tells Kuma to return only the table of contents for the page in HTML. It's returned as an ordered list (that is, {{HTMLElement("ol")}}).

For example: https://developer.mozilla.org/en-US/docs/HTML/HTML5$toc

$json

Tells Kuma to describe the page in a JSON object; this object is essentially the same one you would get using the KumaScript routine wiki.getPage().

For example: https://developer.mozilla.org/en-US/docs/HTML/HTML5$json

$children

Tells Kuma to list the topic children of the page in JSON; this object is essentially the same one you would get using the KumaScript routine pages.subpages().

For example: https://developer.mozilla.org/en-US/docs/HTML/HTML5$children

The PUT API

We are currently testing out a PUT API for writing to wiki pages, but it needs work and might be too early to rely on yet. Try it out and let us know how it works for you!

Revision Source

<h3 id="Introduction">Introduction</h3>
<p>MDN / Kuma doesn't have a central API. Instead, our general approach is to offer ways to turn human-accessible resources into machine-friendly data.</p>
<h3 id="Cross-Origin_Resource_Sharing">Cross-Origin Resource Sharing</h3>
<p>Our intent is to enable <a href="/docs/HTTP/Access_control_CORS" title="/docs/HTTP/Access_control_CORS">CORS</a> on all public data where it's safe to do so - which should include pretty much everything. If you find something that cannot be used with <a href="/docs/HTTP/Access_control_CORS" title="/docs/HTTP/Access_control_CORS">cross-origin requests</a>, that's <a href="https://bugzilla.mozilla.org/form.mdn" title="https://bugzilla.mozilla.org/form.mdn">a bug to be fixed</a>!</p>
<h3 id="Feeds_(RSS_.26_JSON)">Feeds (RSS &amp; JSON)</h3>
<p>Check out the <a href="/docs/Project:Feeds" title="/docs/Project:Feeds">Project:Feeds</a> page, if you're interested in accessing various <a href="/docs/Project:Feeds" title="/docs/Project:Feeds">read-only feeds</a> of data. These include changes to documents, documents by tag, and more. Feel free to <a href="https://bugzilla.mozilla.org/form.mdn" title="https://bugzilla.mozilla.org/form.mdn">file a bug</a> if there's some collection of data you'd like from MDN that we don't yet offer!</p>
<p>Or, better yet: <a href="https://github.com/mozilla/kuma" title="https://github.com/mozilla/kuma">Fork us on GitHub and submit a pull request</a>!</p>
<h3 id="Document_parameters">Document parameters</h3>
<p>We also support several useful query parameter options on every Kuma wiki document URL, when fetched via HTTP GET or viewed in a browser:</p>
<table border="0" class="standard-table" height="608" width="1142">
  <tbody>
    <tr>
      <th style="width:13em">Parameter</th>
      <th>Description</th>
    </tr>
    <tr>
      <td valign="top"><code>?raw</code></td>
      <td valign="top">
        <p>Instructs Kuma to return the raw content of the page, without any of the skin material, such as the headers, footers, and so forth. This does not execute templates or scripts.</p>
        <p>For example: <a href="https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw">https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw</a></p>
      </td>
    </tr>
    <tr>
      <td valign="top"><code>&amp;macros</code></td>
      <td valign="top">
        <p>Instructs Kuma to execute all the templates in the page.</p>
        <p>For example: <a href="https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw&amp;macros">https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw&amp;macros</a></p>
      </td>
    </tr>
    <tr>
      <td valign="top"><code>&amp;include</code></td>
      <td valign="top">
        <p>Tells Kuma to strip out any blocks that have the class "noinclude" on them. This is useful to get the output as it would appear when included in another page, rather than as a standalone page. Often this will remove sample code and the like (although not always).</p>
        <p>For example: <a href="https://developer.mozilla.org/en-US/docs/XUL/Attribute/align?raw&amp;macros&amp;include" title="https://developer.mozilla.org/en-US/docs/XUL/Attribute/align?raw&amp;macros&amp;include">https://developer.mozilla.org/en-US/docs/XUL/Attribute/align?raw&amp;macros&amp;include</a></p>
      </td>
    </tr>
    <tr>
      <td valign="top"><code>&amp;section=[section-id]</code></td>
      <td valign="top">
        <p>Instructs Kuma to return the content from only the section with the specified anchor name.</p>
        <p>For example: <a href="https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw&amp;section=Semantics">https://developer.mozilla.org/en-US/docs/HTML/HTML5?raw&amp;section=Semantics</a></p>
      </td>
    </tr>
  </tbody>
</table>
<h3 id="Document_metadata_resources">Document metadata resources</h3>
<p>Along with parameters to tweak the response of a document URL, there are also some alternate views on documents:</p>
<table border="0" class="standard-table" height="608" width="1142">
  <tbody>
    <tr>
      <td valign="top"><code>$toc</code></td>
      <td valign="top">
        <p>Tells Kuma to return only the table of contents for the page in HTML. It's returned as an ordered list (that is, {{HTMLElement("ol")}}).</p>
        <p>For example: <a href="https://developer.mozilla.org/en-US/docs/HTML/HTML5$toc">https://developer.mozilla.org/en-US/docs/HTML/HTML5$toc</a></p>
      </td>
    </tr>
    <tr>
      <td valign="top"><code>$json</code></td>
      <td valign="top">
        <p>Tells Kuma to describe the page in a JSON object; this object is essentially the same one you would get using the KumaScript routine <code>wiki.getPage()</code>.</p>
        <p>For example: <a href="https://developer.mozilla.org/en-US/docs/HTML/HTML5$json">https://developer.mozilla.org/en-US/docs/HTML/HTML5$json</a></p>
      </td>
    </tr>
    <tr>
      <td valign="top"><code>$children</code></td>
      <td valign="top">
        <p>Tells Kuma to list the topic children of the page in JSON; this object is essentially the same one you would get using the KumaScript routine <code>pages.subpages()</code>.</p>
        <p>For example: <a href="https://developer.mozilla.org/en-US/docs/HTML/HTML5$children
">https://developer.mozilla.org/en-US/docs/HTML/HTML5$children</a></p>
      </td>
    </tr>
  </tbody>
</table>
<h3 id="The_PUT_API">The PUT API</h3>
<p>We are currently testing out <a href="/en-US/docs/User:lmorchard/PUT-API" title="/en-US/docs/User:lmorchard/PUT-API">a PUT API for writing to wiki pages</a>, but it needs work and might be too early to rely on yet. Try it out and let us know how it works for you!</p>
Revert to this revision