PUT-API

  • Revision slug: User:lmorchard/PUT-API
  • Revision title: PUT-API
  • Revision id: 326149
  • Created:
  • Creator: lmorchard
  • Is current revision? No
  • Comment

Revision Content

Overview

The MDN wiki now provides an HTTP PUT API for updating documents in whole or by section. This can be handy for things such as:

  • You can create a page for your project and update content in certain sections from automated build, testing, and deployment scripts. This can help you keep your community up to date with your project's progress.
  • If your project offers documentation alongside source code, you can push HTML renderings into a subsection of MDN. This lets you maintain docs in a way that's appropriate for your team's workflow, while still contributing to MDN and allowing localizers to translate the content.

A word on testing your application against MDN

In developing the software that runs MDN, we host instances of the site on servers in various stages of readiness:

  • Production (http://developer.mozilla.org/), the real site with stable code and where changes to content matter.
  • Staging (http://developer.allizom.org/), a version of the site where changes are throwaway and upcoming features are tested.
  • Development (http://developer-dev.allizom.org/), a version of the site running the absolute latest and untested code.

Accordingly, in order to keep from cluttering up the site with experimental content, you should try developing your application against Staging first. Then, when you are reasonably certain that it'll do what you want, reconfigure it to work against Production. You can also try working against Development, but you may run into issues.

Creating an API key

The first thing you need is an API key. This is a key ID / secret pair that you'll use with HTTP Basic authentication over SSL to enable your application to act on your behalf. This key will do basic usage tracking, so you can see what's been done with it. You can also delete an API key to revoke access, in case a key ID / secret pair has been accidentally exposed to parties who shouldn't have it.

To create an API key, sign into MDN and visit the API keys management page. This page lets you create and delete API keys, as well as inspect recent usage history. You can also get to this page by visiting your profile: Click on your username in the upper right of the site. On your profile page, you should see a "Manage API Keys" button.

Clicking on the "Create a new API key" button should reveal a form with a single text field. You can use the field to describe the purposes for which the key will be used. This is an important field, because nothing else about the key will be visible in the future besides usage history.

After you fill out the text field and click "Create", the randomly generated key ID and secret strings will be displayed. Copy these down somewhere safe (eg. to your application's configuration settings), because the site will never display them again and there is no recovery method. If you lose them, simply delete the API key and create a new one.

 

Revision Source

<p>Overview</p>
<p>The MDN wiki now provides an HTTP PUT API for updating documents in whole or by section. This can be handy for things such as:</p>
<ul>
  <li>You can create a page for your project and update content in certain sections from automated build, testing, and deployment scripts. This can help you keep your community up to date with your project's progress.</li>
  <li>If your project offers documentation alongside source code, you can push HTML renderings into a subsection of MDN. This lets you maintain docs in a way that's appropriate for your team's workflow, while still contributing to MDN and allowing localizers to translate the content.</li>
</ul>
<p>A word on testing your application against MDN</p>
<p>In developing the software that runs MDN, we host instances of the site on servers in various stages of readiness:</p>
<ul>
  <li>Production (http://developer.mozilla.org/), the real site with stable code and where changes to content matter.</li>
  <li>Staging (http://developer.allizom.org/), a version of the site where changes are throwaway and upcoming features are tested.</li>
  <li>Development (http://developer-dev.allizom.org/), a version of the site running the absolute latest and untested code.</li>
</ul>
<p>Accordingly, in order to keep from cluttering up the site with experimental content, you should try developing your application against Staging first. Then, when you are reasonably certain that it'll do what you want, reconfigure it to work against Production. You can also try working against Development, but you may run into issues.</p>
<p>Creating an API key</p>
<p>The first thing you need is an API key. This is a key ID / secret pair that you'll use with HTTP Basic authentication over SSL to enable your application to act on your behalf. This key will do basic usage tracking, so you can see what's been done with it. You can also delete an API key to revoke access, in case a key ID / secret pair has been accidentally exposed to parties who shouldn't have it.</p>
<p>To create an API key, sign into MDN and <a href="https://developer.mozilla.org/en-US/keys/" title="https://developer.mozilla.org/en-US/keys/">visit the API keys management page</a>. This page lets you create and delete API keys, as well as inspect recent usage history. You can also get to this page by visiting your profile: Click on your username in the upper right of the site. On your profile page, you should see a "<a href="https://developer.mozilla.org/en-US/keys/" title="https://developer.mozilla.org/en-US/keys/">Manage API Keys</a>" button.</p>
<p>Clicking on the "Create a new API key" button should reveal a form with a single text field. You can use the field to describe the purposes for which the key will be used. This is an important field, because nothing else about the key will be visible in the future besides usage history.</p>
<p>After you fill out the text field and click "Create", the randomly generated key ID and secret strings will be displayed. Copy these down somewhere safe (eg. to your application's configuration settings), because the site will never display them again and there is no recovery method. If you lose them, simply delete the API key and create a new one.</p>
<p>&nbsp;</p>
Revert to this revision