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 about testing
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 that allows an application to act on your behalf. This key will collect 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.
Note: The above link goes to the Production site, and keys do not work between Production and Staging. You can also get to this page by visiting your profile on the respective site: 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 will be displayed. Copy these down somewhere safe (eg. to your application's configuration settings); the site will never display them again, and there is no recovery method. If you lose them, simply delete the API key and create another.
Making a PUT request
Since the PUT API works by way of plain HTTP, it should be compatible with the application environment and libraries of your choice. So, this first example uses the command-line tool cURL to demonstrate how to issue a simple PUT request to MDN.
# Base URL and API key from staging (example only) MDN_BASE_URL="https://developer.allizom.org" MDN_KEY_ID="frsNFFR3w0yEALRE9IA9oN1KwoDno8vVGrzsBNvCofI" MDN_SECRET="423PdCvnvraH0FkCDTKnizTmKGNkEdgQTi6RlEFTiWs" # Document-specific details DOC_USERNAME="lmorchard" DOC_PATH="/en-US/docs/User:$DOC_USERNAME/PutExample" DOC_TYPE="Content-Type: text/html" DOC_DATA="<b>HELLO WORLD</b>" # Putting it all together... curl -si -X PUT -H"$DOC_TYPE" -d"$DOC_DATA" -u"$MDN_KEY_ID:$MDN_SECRET" "$MDN_BASE_URL$DOC_PATH"
Since there's a lot going on in this cURL invocation, the example is broken into variables:
MDN_BASE_URL- as mentioned before, you should plan to switch your application between staging and production servers on MDN. This variable allows for that.
MDN_KEY_ID- the key ID from the API key you created. Note that these are server-specific - the same keys do not work between staging and production.
MDN_SECRET- the secret from the API key that corresponds with the key ID.
DOC_USERNAME- change this to your MDN username.
DOC_PATH- the URL path to the document with content you want to manipulate.
DOC_TYPE- the content in the request will be
DOC_DATA- the content sent in the PUT request body; this is the content that will be used in a new revision to the document
So, along with the variables, here are some general notes on the example and its use of the PUT API:
- The key ID and secret are supplied as username and password, respectively, in HTTP Basic authentication over SSL.
DOC_PATHfor this example includes a username - presumably yours - but that's just for the sake of example and ensuring you have your own sample page to play with. You can use any URL path to any document on the wiki.
Content-Typeheader is required, and lets MDN know how to process the content sent in the PUT request. Several content types are supported, and this feature will be described in greater detail shortly.
- Content intended for the page is sent in the request body, using the representation promised in the
There are several responses you may see if you try this example:
205. (You may see others, but those suggest something has gone wrong with the site. That will, hopefully, be rare.)
If either the key ID or secret are incorrect, you'll see a
403 Forbidden response. Double check your key details and that you're using the right pair for the right server. Create a new API key, if necessary.
404 Not Found
If you've never created a page at the URL path
/en-US/docs/User:$MDN_USERNAME, you'll see a
404 Not Found response. This is important: The PUT API will not automatically create parent pages. If you're creating a number of pages intended to comprise a subsection of MDN, make sure to create parent pages first from the top down in the hierarchy.
If the parent page exists, but the path itself doesn't, you should see a
201 Created response. This signifies that a new page was created, as opposed to an existing one having been updated.
205 Reset Content
In the case of an updated document, you'll see a
205 Reset Content response. This means that the document content has been updated, and that you should reload the document if you happen to need to see the results. This is important to note: MDN performs certain filtering and processing steps on content, so what you put in may not be exactly what gets served back.
Supported Content Types
The PUT API accepts one of several content types in the request body.
There are actually two forms of
text/html accepted: fragment and document.
An HTML fragment is just an arbitrary chunk of markup, and is used as-is to revise document content. This is the simplest way to update documents.
However, content is treated as an HTML document if it consists of an
<html> element containing
<body> elements. The contents of
<body> is extracted as the content intended as a new revision. From the
<head> element, the contents of
<title> is extracted and used as the title for the document on MDN. This is a more complex way to update documents, but is intended to accomodate submission of existing HTML pages.
text/html content type is handy, there are more fields belonging to documents that are useful to manage. These include the following:
title- the document title
content- the content intended for the new revision
tags- tags used to organize documents
review_tags- tags used to request content reviews
summary- a comment describing the revision to be made
show_toc- a flag (0/1) indicating whether the table of contents should be shown for this document
These fields can be supplied as string values in a JSON-encoded object with the
application/json content-type in a PUT request.
@@TODO: Need a JSON example here.
This content type is handled basically like
application/json - the same fields are accepted. But, it might be less useful than JSON and is supported mainly for testing purposes.
Updating a single section
Normally, an HTTP PUT request replaces the entirety of a document with the submitted content in a new revision. However, you can use the query parameter
?section to constrain revision to a single section of the page and leave the rest of the content as-is. This is handy for automating changes to one part of a document that is otherwise managed by hand, or even for aggregating changes from many sources into one page.
Breaking a document into sections
@@TODO: Show an HTML example with headers, here.
Specifying a section in a PUT request
@@TODO: Show how to get IDs for sections from the table of contents