3.2 予約プロパティ
x-www-form-urlencodedやmultipart/form-dataでリクエストを送信する場合、一部のPOSTボディプロパティ名は予約されています。
access_token - リクエストの認証に用いられるOAuthベアラートークン（アクセストークンはHTTP
Authorizationヘッダーまたはこのフォームパラメータとして送信可能）h - 作成するオブジェクトタイプを指定するために使うaction -
deleteまたはundelete（フォームエンコード構文では更新はサポートされません）を示す
url - 対象となるオブジェクトのURLを示すmp-* - 将来的な利用のために予約
x-www-form-urlencodedまたはmultipart/form-dataリクエストで投稿を作成する際、それ以外のプロパティはすべて作成されるオブジェクトのプロパティとみなされます。
サーバーはMUST
NOTaccess_tokenプロパティを投稿に保存してはいけません。
mp-で始まるプロパティは、クライアントがサーバーにコマンドを送る仕組みのために予約されています。通常、投稿のプロパティはユーザーに表示されますが、サーバーへのコマンドはユーザーには表示されず、投稿のプロパティとして意味がありません。新しいmp-コマンドの実験を行いたいクライアントやサーバーは、indieweb.org/Micropub-extensionsでアイディアを出し合い、実装を文書化することを推奨します。
JSON構文で投稿を作成する場合も、mp-で始まるプロパティは上記の通り予約されています。
3.3 作成
投稿を作成するには、作成する投稿タイプとそのプロパティを指定してMicropubエンドポイントにHTTP
POSTリクエストを送信します。タイプが指定されていない場合は、デフォルトタイプ[h-entry]をSHOULD使うべきです。クライアントとサーバーは、x-www-form-urlencoded構文による投稿作成をMUSTサポートし、JSON構文による投稿作成もMAYサポートできます。
h={Microformats object type}
例：h=entry
"mp-"で始まらないすべてのパラメータは作成対象オブジェクトのプロパティです。
例：content=hello+world
h-entryなどでプロパティに複数の値（例：複数カテゴリ）を指定するには、プロパティ名の末尾に角括弧を付けて配列であることを示します。
例：category[]=foo&category[]=bar
複数値をとるプロパティは、角括弧の有無に関わらず、単一値もMUST受け付けなければなりません。以下にフォームエンコードリクエストの完全な例を示します。
例 1
h=entry&content=hello+world&category[]=foo&category[]=bar
3.3.1 ファイルのアップロード
ファイルをアップロードする場合は、クライアントはMedia Endpointの存在をMUST確認してください。Media
Endpointが無い場合、Micropubエンドポイントでファイルが直接受け付けられるとみなしそのままリクエストを送れます。ファイルをMicropubエンドポイントにアップロードするには、リクエスト全体をmultipart/form-data形式で作成し、ファイルは標準プロパティとして送信します。
例として、キャプション付き写真をアップロードする場合、h、content、photoの3つのパートを含めます。
例 2
multipart/form-data; boundary=553d9cee2030456a81931fb708ece92c
--553d9cee2030456a81931fb708ece92c
Content-Disposition: form-data; name="h"
entry
--553d9cee2030456a81931fb708ece92c
Content-Disposition: form-data; name="content"
Hello World!
--553d9cee2030456a81931fb708ece92c
Content-Disposition: form-data; name="photo"; filename="aaronpk.png"
Content-Type: image/png
Content-Transfer-Encoding: binary
... (binary data) ...
--553d9cee2030456a81931fb708ece92c--
photoやvideoなどファイルアップロードを受け付けるプロパティは、ファイルのURL値も同等として受け付けるMUSTがあります。エンドポイントはURL先のファイルを[Fetch]でダウンロードし、アップロードと同じように保存してもMAYです。例：
例 3
h=entry&content=hello+world&photo=https%3A%2F%2Fphotos.example.com%2F592829482876343254.jpg
これはMedia Endpoint経由でファイルをアップロードする場合や、外部画像を参照する場合などのためのものです。詳細はMedia Endpointセクションを参照してください。
```html
3.3.2 JSON構文
プロパティのより複雑な値を扱うために、解析済みMicroformats 2 JSONフォーマットでエントリを送信することで、JSON構文で投稿を作成できます。
この場合、ファイルを同時にアップロードすることはできず、前述のようにURLでファイルを参照することだけが可能です。
JSON形式で投稿を作成する場合、すべての値は一つだけでも配列形式で指定しなければならず、Microformats 2
JSONフォーマットと同様です。このリクエストはapplication/jsonコンテンツタイプで送信します。
mp-で始まるプロパティは、予約プロパティの説明の通り予約されています。
例 4
POST /micropub HTTP/1.1
Host: aaronpk.example
Content-type: application/json
{
"type": ["h-entry"],
"properties": {
"content": ["hello world"],
"category": ["foo","bar"],
"photo": ["https://photos.example.com/592829482876343254.jpg"]
}
}
altテキスト付き画像のアップロード
アップロードする画像にaltテキストを付加するには、Microformats
2構文を用いてphotoプロパティの画像URLおよびaltテキストを指定できます。値にURLのみでなく、valueにURL、altにテキストを持つオブジェクトを使います。photoの値がオブジェクトとなるため、フォームエンコードやマルチパートリクエストは利用できません。まず写真をMedia
Endpointへアップロードし、そのURLをJSONリクエストに記載する必要があります。下の例を参照してください。
例 5
POST /micropub HTTP/1.1
Host: aaronpk.example
Content-type: application/json
{
"type": ["h-entry"],
"properties": {
"content": ["hello world"],
"category": ["foo","bar"],
"photo": [
{
"value": "https://photos.example.com/globe.gif",
"alt": "Spinning globe animation"
}
]
}
}
警告
altテキスト指定方法は、画像altテキストの表現方法に関するMicroformats 2提案(issue
2)が組み込まれることを想定して追加されました。これが別の方法で解決された場合はMicropub仕様もそれに合わせて調整されるべきです。
3.3.4 双方向テキスト
Micropubリクエストの自然言語値はMAY双方向テキストを含むことができます。Micropubテキスト値のデフォルトの基底方向は左から右です。個々の自然言語値の基底方向は、下記の方法で明示的に変更MAYできます。
自然言語値で双方向テキストを指定し、かつその基底方向がそのテキストの最初の強い方向性文字で正しく特定できない場合([BIDI])、公開クライアントはその値の前にUnicode双方向制御文字を付加するか、HTML値の場合はHTML方向属性を使って明示的に基底方向を特定するSHOULDです。
双方向テキストを含む自然言語値を受け入れるMicropubサーバーは、プレーンテキスト値の場合は最初の強い方向性文字のスキャン、HTML値の場合は方向属性やタグ外の最初の強い方向性文字のスキャンを用いて、任意の自然言語値の基底方向を特定するSHOULDです。これらの自然言語値を表示する際、サーバーは[BIDI]アルゴリズムに従い、適切なコンテンツレンダリングをMUST判定し、必要に応じて文字列の周囲に制御文字やマークアップを追加して基底方向を示す必要があります。
3.3.5 未認識プロパティ
リクエストにサーバーが認識しないプロパティが含まれている場合、サーバーは未認識のプロパティを無視しなければならず、認識した値で投稿を作成します。
これにより、クライアントはサポートするサーバーにはリッチなコンテンツを投稿し、サポートしないサーバーにもフォールバックコンテンツを投稿することができます。
たとえば、クライアントがweightプロパティにh-measure値を持つ体重測定投稿と、summaryプロパティにプレーンテキストの要約を含んだ投稿を作成した場合、サーバーがweightプロパティを認識しない場合はこれを単に無視し、summaryのみを持つプレーンテキスト投稿として作成します。
3.3.6 レスポンス
投稿が作成された場合、MicropubエンドポイントはHTTP 201
CreatedステータスコードまたはHTTP 202
Acceptedコードを返し、作成された投稿のURLを示すLocationヘッダーを必ず返さなければなりません。[RFC2616]
例 7
HTTP/1.1 201 Created
Location: https://aaronpk.example/post/1000
エンドポイントがリクエストを即時処理せず非同期で処理・保存することを選択した場合、HTTP 202
Acceptedステータスコードと、同様にLocationヘッダーを返す必要があります。サーバーはHTTP
202返却前に、オブジェクトが確実に作成されることを担保するためにエラーチェックおよびバリデーション処理を同期的に行う必要があります。クライアントはHTTP 202レスポンスを受け取った場合、指定URLに将来（近いうちに）対象オブジェクトが存在することを期待します。
ターゲットがショートリンクや他の場所へのシンジケーション投稿も提供する場合は、MicropubエンドポイントはHTTP
Linkヘッダーで適切な"rel"値を付与し追加URLを返してもかまいません。たとえば、投稿のショートURLを返す場合：
Link: <http://aaron.pk/xxxxx>; rel="shortlink"
または、シンジケーション投稿のURLを含める場合：
Link: <https://myfavoritesocialnetwork.example/aaronpk/xxxxxx>; rel="syndication"
エラー応答
エラー発生時の指示方法は、下記「エラー応答」セクションを参照してください。
3.4 更新
Micropubサーバーは、ここで説明するような個々のプロパティの追加や削除を含む投稿の更新操作をサポートすることが推奨されます。
エントリの更新は、変更内容を記述したJSON投稿によって実現します。
エントリを更新するには、"action": "update"を送り、更新対象エントリのURLを"url"プロパティで指定します。リクエストには更新内容を示すreplaceや
add、deleteプロパティ（またはこれらの任意の組み合わせ）を必ず含めてください。
replaceやadd、deleteキーの各プロパティ値は、値が1つだけでも常に配列形式で指定しなければなりません。
同一リクエスト内でadd/delete操作を組み合わせることは可能ですが、それぞれ別のプロパティ-値の組合せを対象とする場合のみに意味があります。同じプロパティ-値組合せに対する複数操作は、サーバーによっては未定義の動作となる可能性があります。
3.4.1 置換
プロパティのすべての値を置換します。プロパティが存在しない場合は作成されます。
例 8
{
"action": "update",
"url": "https://aaronpk.example/post/100",
"replace": {
"content": ["hello moon"]
}
}
この操作はエントリ全体のcontentを新しいテキストで置き換えます。他のプロパティはそのまま残ります。
3.4.2 追加
このプロパティに既存の値があれば、それらは変更せず、新しい値が追加されます。プロパティが存在しない場合は作成されます。
シンジケーションURLの追加
ユースケース：投稿後にシンジケーションリンクを追加する場合。たとえば、クライアントがまず投稿し、その後でMyFavoriteSocialNetworkやWikimediaにシンジケートする場合、サイトは新しいシンジケーションURLで元の投稿を更新する手段が必要です。
シンジケーションURLを追加するには、更新リクエスト内に1つ以上のURLを含めます。
例 9
{
"action": "update",
"url": "https://aaronpk.example/2014/06/01/9/indieweb",
"add": {
"syndication": ["http://web.archive.org/web/20040104110725/https://aaronpk.example/2014/06/01/9/indieweb"]
}
}
ユースケース：投稿作成後にタグを追加する場合。
カテゴリ等のプロパティに複数値を追加するには、新しい値を配列で指定します。
例 10
{
"action": "update",
"url": "https://aaronpk.example/2014/06/01/9/indieweb",
"add": {
"category": ["micropub","indieweb"]
}
}
3.4.3 削除
プロパティが存在する場合、それを削除します。指定したプロパティ全体を完全に削除します。
例 11
{
"action": "update",
"url": "https://aaronpk.example/2014/06/01/9/indieweb",
"delete": ["category"]
}
カテゴリなど複数値のプロパティについては、値単位で個別に削除可能です。残る値がなければプロパティそのものが削除されます。
例 12
{
"action": "update",
"url": "https://aaronpk.example/2014/06/01/9/indieweb",
"delete": {
"category": ["indieweb"]
}
}
3.4.4 レスポンス
サーバーは、更新リクエストが成功した場合、HTTP 200、201 または 204で応答しなければなりません。更新操作により投稿のURLが変更された場合、サーバーはHTTP 201で応答し、新しいURLをHTTP
Locationヘッダーで必ず含める必要があります。それ以外の場合は、レスポンスボディ有無に応じて200または204を返します。レスポンスにボディは不要ですが、行った変更内容を記載するJSONオブジェクトが含まれてもかまいません。
3.5 削除
Micropubサーバーは、投稿の削除をサポートすべきであり、未削除（undelete）投稿のサポートもしてもよいです。
あるURLのエントリー全体を削除するには、action=deleteと削除対象アイテムのURLをurlプロパティに含めてPOSTリクエストを送信します。
例 13
action=delete
&url=https:
例 14
{
"action": "delete",
"url": "https://aaronpk.example/2014/06/01/9/indieweb"
}
投稿を未削除（undelete）するには、"undelete" をアクションとして使用します。
例 15
action=undelete
&url=https:
例 16
{
"action": "undelete",
"url": "https://aaronpk.example/2014/06/01/9/indieweb"
}
3.5.1 レスポンス
サーバーは、削除や未削除リクエストが成功した場合、HTTP 200, 201 または 204 で応答しなければなりません。未削除操作により投稿のURLが変更された場合、サーバーはHTTP
201で応答し、新しいURLをHTTPLocationヘッダーに含める必要があります。そうでなければ、レスポンス本文に内容があるかどうかに応じて、サーバーは200または204で応答します。レスポンスで本文は不要ですが、変更内容を記述したJSONオブジェクトを含めても構いません。
3.7 クエリ
Micropubクライアントは、エンドポイントの機能を発見したり（たとえばユーザー表示用のシンジケーションターゲットリストの取得や、投稿情報の取得など）、Micropubエンドポイントへクエリを投げる必要がある場合があります。
クエリする場合は、MicropubエンドポイントにGETリクエストし、qパラメータで取得したい内容を指定します。
注
MicropubエンドポイントURLにクエリパラメータ（例：?micropub=endpoint）が既に含まれる場合、クライアントは既存クエリを置き換えず追記する形でqパラメータを付与しなければなりません。
3.7.1 設定
ユーザーがMicropubクライアントに初回ログインした際、クライアントはエンドポイントに関する初期情報を問い合わせる必要があります。クライアントはq=configでクエリ要求し初期設定情報を取得すべきです。
サーバーは設定レスポンスで下記情報を含めるべきです。
- サポートしているシンジケーションエンドポイント（プロパティ名：
syndicate-to。レスポンス構造はシンジケーションターゲット参照）
- サポートしている場合はメディアエンドポイント（プロパティ名：
media-endpoint）
例 20
GET /micropub?q=config
Authorization: Bearer xxxxxxxxx
Accept: application/json
HTTP/1.1 200 OK
Content-type: application/json
{
"media-endpoint": "https://media.example.com/micropub",
"syndicate-to": [
{
"uid": "https://myfavoritesocialnetwork.example/aaronpk",
"name": "aaronpk on myfavoritesocialnetwork",
"service": {
"name": "My Favorite Social Network",
"url": "https://myfavoritesocialnetwork.example/",
"photo": "https://myfavoritesocialnetwork.example/img/icon.png"
},
"user": {
"name": "aaronpk",
"url": "https://myfavoritesocialnetwork.example/aaronpk",
"photo": "https://myfavoritesocialnetwork.example/aaronpk/photo.jpg"
}
}
]
}
サーバーは設定クエリをサポートし、そのサーバーに関連する全てのプロパティを返すべきです。該当するプロパティがなければ、レスポンスは空のJSONオブジェクト{}であるべきです。
クライアントは想定外のレスポンスも空レスポンスとみなして処理し、サポートしていないサーバーからの予期しない応答にも対応すべきです。たとえば設定クエリ非対応サーバーはHTTP
400レスポンスを返す場合もありますが、それも空JSONオブジェクトと同等に扱うべきです。
3.7.2 ソースコンテンツ
Micropubクライアントは、エンドポイントに特定の投稿プロパティのクエリを送信できます。これにより、例えばタグ追加用インターフェース等、必要なプロパティのみをリクエストし取得できます。
投稿の更新に対応しているサーバーは、ソースコンテンツクエリをサポートしなければなりません。
クエリには、MicropubエンドポイントへGETリクエストを送り、qパラメータにsourceを指定し、urlパラメータで投稿のURLを指定します。リクエストするプロパティ名は、propertiesキーで一つ以上指定でき、複数なら[HTML5]のURLエンコーディング規則どおり配列ブラケット記法で指定します。
エンドポイントは、[microformats2-parsing] [JSON]形式で、propertiesオブジェクトにクエリ対象プロパティ名をキーとして返します。何も指定しない場合、すべてのプロパティと、投稿種類のtypeプロパティを含めて返す必要があります。
例 21
GET /micropub?q=source&properties[]=published&properties[]=category&url=https:
Authorization: Bearer xxxxxxxxx
Accept: application/json
HTTP/1.1 200 OK
Content-type: application/json
{
"properties": {
"published": ["2016-02-21T12:50:53-08:00"],
"category": [
"foo",
"bar"
]
}
}
例 22
GET /micropub?q=source&url=https:
Authorization: Bearer xxxxxxxxx
Accept: application/json
HTTP/1.1 200 OK
Content-type: application/json
{
"type": ["h-entry"],
"properties": {
"published": ["2016-02-21T12:50:53-08:00"],
"content": ["Hello World"],
"category": [
"foo",
"bar"
]
}
}
HTML コンテンツ
投稿ソースがHTMLだった場合、エンドポイントはcontentプロパティをhtmlプロパティを持つオブジェクトで返さなければなりません。それ以外の場合、contentプロパティは文字列値で返し、クライアント側ではプレーンテキストとみなします。この挙動は[microformats2-parsing]の値仕様に準拠します。
以下はHTMLで記述された投稿内容を取得する例です。
例 23
GET /micropub?q=source&properties=content&url=https:
Authorization: Bearer xxxxxxxxx
Accept: application/json
HTTP/1.1 200 OK
Content-type: application/json
{
"properties": {
"content": [
{
"html": "<b>Hello</b> <i>World</i>"
}
]
}
}
3.7.3 シンジケーションターゲット
サポートされているシンジケーションターゲット一覧を返すには、qパラメータをsyndicate-toに設定します。
GET /micropub?q=syndicate-to
エンドポイントは、[JSON]形式で、キーsyndicate-toの値として対応シンジケーションターゲットを記述したオブジェクト配列を返さなければなりません（MUST）。どのエンドポイントも未定義の際は、値は空の配列[]とすべきです（SHOULD）。
最低限、シンジケーションターゲットはuidと表示用nameプロパティを持つ必要があります。uidはMicropubエンドポイント固有の一意識別子で、エンドユーザーには見せる意図がありません。nameは投稿画面で表示しやすい人間向け説明文とします。
シンジケーションターゲットは、シンジケーション先サービス情報やユーザーアカウント情報をservice,
userプロパティとしてオプションで含めても構いません。service・userオブジェクトはともに、表示用nameプロパティが必須で（MUST）、オプションでurlおよびphotoを含めてもよいです（MAY）。クライアントはnameとphotoを使いシンジケーション選択のUI表示を向上できます。
例 24
GET /micropub?q=syndicate-to
Authorization: Bearer xxxxxxxxx
Accept: application/json
HTTP/1.1 200 OK
Content-type: application/json
{
"syndicate-to": [
{
"uid": "https://archive.org/",
"name": "archive.org"
},
{
"uid": "https://wikimedia.org/",
"name": "WikiMedia"
},
{
"uid": "https://myfavoritesocialnetwork.example/aaronpk",
"name": "aaronpk on myfavoritesocialnetwork",
"service": {
"name": "My Favorite Social Network",
"url": "https://myfavoritesocialnetwork.example/",
"photo": "https://myfavoritesocialnetwork.example/img/icon.png"
},
"user": {
"name": "aaronpk",
"url": "https://myfavoritesocialnetwork.example/aaronpk",
"photo": "https://myfavoritesocialnetwork.example/aaronpk/photo.jpg"
}
}
]
}
最低限、シンジケーション先はuidおよびnameプロパティが必要です。uidプロパティはクライアントから見て不透明な値で、Micropubリクエストでターゲット指定するために利用します。nameはユーザー表示用で、複数の同一サービス先がある場合は区別可能な内容であるべきです。
Micropubサーバーは、シンジケーション先のさらなる情報（サービス・ユーザーアカウント）も追加可能です。これはserviceおよびuserプロパティで指定し、それぞれname（人間向け名）・url・photo（URL形式）を格納できます。
クライアントは、表示を向上させるためにserviceやuserの内容（アイコンなど）をシンジケーションボタン等に利用しても構いません。
投稿のシンジケーションに対応するサーバーはsyndicate-toクエリに対応すべきです。
3.8 エラーレスポンス
リクエストに問題があった場合、エンドポイントは適切なHTTPステータスコード（通常は400, 401, 403）を返し、説明も含めても構いません。エラー本文を返す場合、レスポンスボディは[JSON]オブジェクトでエラー内容を示すerrorプロパティを必ず一つ含めます。以下のエラーコードが定義されています：
- HTTP 403:
"error":"forbidden" - 認証ユーザーに実行権限がありません。
- HTTP 401:
"error":"unauthorized" - リクエストにアクセストークンがありません。なおHTTP
401と403の違いに注意：403はアクセストークンありだが権限が足りない場合のみ返すべきです。
- HTTP 401:
"error":"insufficient_scope" -
トークンのスコープがリクエストに必要な範囲を満たしていません。クライアントは再認可を促す場合があります。"scope"属性で成功に必要なスコープを記載しても可。
- HTTP 400:
"error":"invalid_request" -
必須パラメータなし、またはパラメータの値に問題があった場合
クライアントは想定外のerror値も汎用エラーとして扱うべきです。レスポンスボディには人間向けエラー内容を知らせるerror_descriptionプロパティも含めてよいですが、これはエンドユーザーではなく開発者向けです。
エラーレスポンスの詳細はOAuth 2 Bearer Token [RFC6750]仕様を参照してください。
例 25
GET /micropub?q=source&url=https:
Authorization: Bearer xxxxxxxx
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"error": "invalid_request",
"error_description": "The post with the requested URL was not found"
}
1.1 Social Web作業グループ
Micropubは、Social Web作業グループによって開発されているいくつかの関連仕様の一つです。別のアプローチや補完的なプロトコルに関心のある実装者は、ActivityPubや概要ドキュメント [social-web-protocols] を参照してください。