--- title: PUT API slug: orphaned/MDN/Tools/PUT_API tags: - Advanced - Automation - Documentation - Draft - Guide - MDN Meta - PUT API - Page-level - Tools translation_of: MDN/Tools/PUT_API original_slug: MDN/Tools/PUT_API ---
{{MDNSidebar}}
 {{draft}}

MDN Wiki はページの全体、または一部の更新のための実験的な HTTP PUT API を提供しています。この機能は、次のような時に便利です:

アプリケーションをテストする

MDN を実行するソフトウェアを開発する中で、次のようにいろいろなステージ上のサイトインスタンスをホストしています:

プロダクションサイトを無駄にしないようにするには、まずステージングに対してアプリケーションを開発する必要があります。それから、あなたが望むことを合理的に実行することができたら、それをプロダクションに反映するように再構成します。また、開発に取り組むこともできますが、問題が発生する可能性があります。

API キーを作成する

APIキーを使うと、毎回 Persona ログインするような介入を要求せずに、アプリケーションを代理人として動作させることができます。SSL 上の HTTP ベーシック認証を使ってユーザー名とパスワードを提供します。基本的な使用のトラッキングを集めて、どのように使われているかがわかるようにします。そして、たまたま持つべきでない人々に渡った場合は、アクセスを無効にするよう API キーを削除できます。

If you have the correct privileges to do so, 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.  Only Mozillians in good standing can currently get API keys, since they grant abilities to automate changes to content rapidly, so unprivileged users must request the ability by filing a bug.

{{NoteStart}}The above link goes to the Production site, and the same 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.{{NoteEnd}}

From there, clicking on the "Create a new API key" button should take you to an entry form so you can submit a request for an API key.

After filling out and submitting the form, you will receive a key ID and secret. These are your username and password, respectively. 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.

PUT リクエストを作成する

Since the PUT API works by way of HTTP, it should be compatible with the application environment and libraries of your choice. This first example uses the command-line tool cURL and a UNIX shell to demonstrate how to issue a simple PUT request to MDN.

リクエスト

# Base URL and API key from staging (example only; substitute your own)
MDN_BASE_URL="https://developer.allizom.org"
MDN_KEY_ID="frsNFFR3w0yEALRE9IA9oN1KwoDno8vVGrzsBNvCofI"
MDN_SECRET="423PdCvnvraH0FkCDTKnizTmKGNkEdgQTi6RlEFTiWs"

# Document-specific details
DOC_USERNAME="lmorchard"  # Change this to your name
DOC_PATH=/ja//docs/User:$DOC_USERNAME/PutExample"
DOC_TYPE="text/html"
DOC_DATA="<b>HELLO WORLD</b>"

# Putting it all together...
curl -si -X PUT -H"Content-Type: $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:

So, along with the variables, here are some general notes on the example and its use of the PUT API:

レスポンス

There are several responses you may see if you try this example: 403, 404, 201, or 205. (You may see others, but those suggest something has gone wrong with the site. That will, hopefully, be rare.)

403 Forbidden

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 document at the URL path /en-US/docs/User:$MDN_USERNAME, you'll see a 404 Not Found response.

{{NoteStart}}The PUT API will not automatically create parent documents. If you're creating a number of documents intended to comprise a subsection of MDN, make sure to create parent documents first from the top down in the hierarchy.{{NoteEnd}}

201 Created

If the parent document exists, but the path itself doesn't, you should see a 201 Created response. This signifies that a new document 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.

{{NoteStart}}MDN performs certain filtering and processing steps on content, so what you put in may not be exactly what gets served back.{{NoteEnd}}

サポートされるコンテンツのタイプ

The PUT API accepts one of several content types in the request body.

text/html

There are actually two forms of text/html accepted: fragment and document.

Fragment

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.

Document

However, if the request body consists of an <html> element containing <head> and <body> elements, it's treated as a full HTML document. In this case, the following processing happens:

This is a more complex way to update documents, but is intended as a convenience to accomodate submission of existing HTML pages.

application/json

Although the text/html content type is handy, there are more fields belonging to documents that are useful to manage. These include the following:

These fields can be supplied as string values in a JSON-encoded object with the application/json content-type in a PUT request.

# Auth Stuff
DOC_USERNAME="lmorchard"  # Change this to your name
MDN_KEY_ID="frsNFFR3w0yEALRE9IA9oN1KwoDno8vVGrzsBNvCofI"
MDN_SECRET="423PdCvnvraH0FkCDTKnizTmKGNkEdgQTi6RlEFTiWs"

# Base Settings (for Staging Env)
MDN_BASE_URL="https://developer.allizom.org"
DOC_PATH=/ja//docs/User:$DOC_USERNAME/PutExample"
DOC_TYPE="application/json"

# Doc Content
echo '{"content": "<b>Hello World</b>", "title": "New Sample Title", "show_toc": 1, "tags": "Beginner, Tutorial", "review_tags": "editorial, technical", "summary": "Sample JSON update from the API"}' > /tmp/mdn.json

# Submitting Content
curl -X PUT -H "Content-Type: $DOC_TYPE" -d @/tmp/mdn.json -u"$MDN_KEY_ID:$MDN_SECRET" "$MDN_BASE_URL$DOC_PATH"

multipart/form-data

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.

1 つのセクションを更新する

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 document 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 or scripts into one document.

文書のセクションを作成する

Documents on MDN can be broken up into sections. These sections are useful for building a table of contents, linking to specific parts, and editing subsets of document content.

Using headers

Headers (ie. <h2> .. <h6>) make sections in MDN documents. The text of each header is transformed automatically into an ID, and that's used for anchor links in the table of contents sidebar on most documents. Those auto-generated IDs can be overriden with the name attribute on headers. Either way, looking at the table of contents is the easiest way to see how a document is broken up into sections, and to discover the IDs for those sections.

The contents of a section include its header and everything following the header up to (but not including) another header of the same or higher level. So, a section that starts with an <h2> continues until the next <h2>, including any subsections started by <h3> .. <h6>. That also means sections can be nested: An <h3> appearing after an <h2> creates a subsection, including any further nested subsections started by <h4> .. <h6>, up to the next <h3> or <h2>.

@@TODO: Show an HTML example with headers, here. This is a bit confusing.

Using container elements

Setting an id attribute on a container element (eg. a <div> or <span> or <section>) in the source editor also creates a section, at least with respect to the PUT API. This is a bit more advanced and requires manual changes to raw HTML, rather than using the WYSIWYG editor. But, if you want to update a chunk of the page without the need for headers, this is how to do it.

セクションを指定する