2.1.1 发布客户端

符合规范的 Micropub 发布客户端需：

• 必须 支持发送 x-www-form-urlencoded 请求
• 必须 支持 [h-entry] 词汇表
• 如果客户端通过上传附件文件来创建文章，则 必须 检查是否存在媒体端点（Media Endpoint），如存在，则应将文件发送到该端点而不是 Micropub 端点
• 推荐 处理服务器错误消息时应表现优雅，并给用户有帮助的提示
• 推荐 支持 端点发现

2.1.2 编辑客户端

符合规范的 Micropub 编辑客户端需：

• 必须 支持发送 JSON 编码请求
• 必须 支持 [h-entry] 词汇表

2.1.3 服务器

符合规范的 Micropub 服务器需：

• 必须 同时支持通过请求头和表单参数两种 认证方式
• 必须 支持使用 [h-entry] 词汇表 创建 文章
• 必须 支持 创建 文章使用 x-www-form-urlencoded 语法
• 推荐 支持 更新 和 删除 文章
• 如服务器支持文章更新功能，则 必须 支持 JSON 语法 和 源内容查询
• 如服务器未指定媒体端点，则 必须 支持使用 multipart/form-data 请求 创建 文章
• 如服务器指定了媒体端点，则 必须 支持 配置查询，其他服务器则 推荐 支持配置查询

2.2.1 客户端

Micropub 客户端指能向服务器发送 Micropub 请求以创建或操作文章的实现。一致性标准见上文一致性类别。

2.2.2 服务器

Micropub 服务器指可根据 Micropub 请求创建，或可选地编辑、删除文章的实现。Micropub 服务器 可以 同时支持用于文件上传的媒体端点（Media Endpoint）。一致性标准见上方一致性类别。

2.2.3 独立性

每个实现必须由不同的团队开发，不得共享、复用或派生自其他合格实现的代码。与本规范实现无关的代码可不受此限制。

2.2.4 互操作性

当服务器按功能要求执行客户端的请求操作、客户端从服务器获得预期响应，且服务器也按要求向客户端返回响应时，则认为某单项功能的客户端和服务器实现可互操作。

2.2.5 实现

Micropub 实现指满足以下所有条件的客户端或服务器：

• 实现了规范中相应一致性类别的功能
• 以可下载软件或托管服务的形式公开对外提供
• 不是实验性的（即面向广泛用户且可日常使用）
• 适合个人作为其网站的主力实现

2.2.6 功能

为评估退出标准，每项下列内容视为一个功能：

• 根据用户的资料页面 URL 发现 Micropub 端点
• 通过 HTTP Authorization 头部包含访问令牌认证请求
• 通过 x-www-form-urlencoded 请求体包含访问令牌认证请求
• 通过要求访问令牌包含至少一个 OAuth 2.0 scope 限制创建文章的权限
• 使用 x-www-form-urlencoded 语法和一个或多个属性创建文章
• 使用 JSON 语法和一个或多个属性创建文章
• 使用 x-www-form-urlencoded 语法为同一属性名创建多个值的文章
• 使用 JSON 语法为同一属性名创建多个值的文章
• 使用 JSON 语法并包含嵌套的 Microformats2 对象创建文章
• 向指定媒体端点上传文件
• 通过 multipart/form-data 方式向 Micropub 端点发送请求并上传文件创建文章
• 通过 URL 引用照片创建文章
• 通过包含图片 alt 文本的 URL 引用照片创建文章
• 请求中包含服务器未识别属性时创建文章
• 创建文章时返回 HTTP 201 Created 及 Location 头部
• 创建文章时返回 HTTP 202 Created 及 Location 头部
• 更新文章并替换某属性的所有值
• 更新文章并向属性添加一个值
• 更新文章并从属性中移除某个值
• 更新文章并移除某个属性
• 更新文章时返回 HTTP 200 OK
• 如更新导致文章 URL 变更时，返回 HTTP 201 Created
• 更新文章时返回 HTTP 204 No Content
• 使用 x-www-form-urlencoded 语法删除文章
• 使用 JSON 语法删除文章
• 使用 x-www-form-urlencoded 语法取消删除（undelete）文章
• 使用 JSON 语法取消删除（undelete）文章
• 将照片上传到媒体端点并在创建文章时使用返回的 URL
• 通过 q=config 查询 Micropub 端点以获取媒体端点和联合发布目标（如有）
• 通过 q=syndicate-to 查询 Micropub 端点以获取联合发布目标列表
• 不带属性列表查询 Micropub 端点获取文章源内容
• 仅查询特定属性时查询 Micropub 端点获取文章源内容

3.1.1 表单编码与多部分请求

针对 x-www-form-urlencoded 和 multipart/form-data 请求，Micropub 扩展了标准的 URL 编码，增加了对多值属性的显式指示。即，如果需要对某属性发送多个值，必须 在属性名后加上方括号 []。

例如，要给 "category" 属性指定多个值，请求中应为 category[]=foo&category[]=bar。

服务器端应将其转换为内部数组结构。对应的 JSON 表达例如下：

{
  "category": [
    "foo",
    "bar"
  ]
}

在多部分请求中同样适用，每个值给在请求的独立“部分”，并使用类似 Content-Disposition: form-data; name="category[]" 的行指明名称。

注意，对 x-www-form-urlencoded 语法的唯一扩展就是增加方括号以表示数组。不支持 foo[0] 和 foo[bar] 这种语法，因此对于更复杂的对象，客户端应使用 JSON 语法 提交。

3.3.1 文件上传

上传文件时，客户端 必须 检查是否存在 媒体端点。如无媒体端点，则可假定 Micropub 端点可直接接收文件，并可直接向其发起请求。上传文件时，整个请求采用 multipart/form-data 格式，并以标准属性名发送文件。

例如，要上传一张带标题的照片，需发送包含 h、content 和 photo 三个部分的请求。

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），Micropub 端点 必须 也接受 URL 值，并将其视同于直接上传。端点 可以 通过 [Fetch] 下载该 URL 的文件副本，并与直接上传存储一致。例如：

h=entry&content=hello+world&photo=https%3A%2F%2Fphotos.example.com%2F592829482876343254.jpg

这是为了支持通过媒体端点或通过引用其它外部图片进行文件上传。更多信息见 媒体端点 章节。

3.3.2 JSON 语法

为支持属性的更复杂取值，你可以以 JSON 语法在解析后的 Microformats 2 JSON 格式中发送数据创建文章。

注意此时不能直接上传文件，只能按照前述以 URL 形式引用文件。

使用 JSON 格式创建文章时，所有值 必须以数组形式指定，即使只有一个值，与 Microformats 2 JSON 格式一致。请求需声明内容类型为 application/json。

以 mp- 开头的属性依 保留属性 规定保留。

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 需要对象型值，不能用 form-encoded 或 multipart 请求实现。请先将图片上传至媒体端点，再在 JSON 请求中引用 URL，如下所示。

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"
      }
    ]
  }
}

3.3.3 嵌套 Microformats 对象

如非必要，应尽量避免使用嵌套 Microformats 对象。更优做法是通过 URL 引用对象。例如在签到或标记照片时引用 h-card 场所等对象，建议先创建对象并用其 URL 引用。

这种方式使每个创建的对象都拥有独立 URL（即每条数据都有自己的链接），也方便服务器单独处理各个实体。例如某场所已存在时可以返回已有对象的链接，也可能先合并新数据再返回。

如果嵌套对象没有 URL 意义，比如发布 h-measure 类型值时，无需为 h-measure 分配 URL，这时可接受使用嵌套对象语法。

嵌套对象要求请求采用 JSON 格式，因为表单编码语法无法一致支持嵌套对象。

下例新建一条“体重”记录（h-entry 类型），其 weight 和 bodyfat 属性为 h-measure 嵌套对象。

{
  "type": ["h-entry"],
  "properties": {
    "summary": [
      "Weighed 70.64 kg"
    ],
    "weight": [
      {
        "type": ["h-measure"],
        "properties": {
          "num": ["70.64"],
          "unit": ["kg"]
        }
      }
    ],
    "bodyfat": [
      {
        "type": ["h-measure"],
        "properties": {
          "num": ["19.83"],
          "unit": ["%"]
        }
      }
    ]
  }
}

3.3.4 双向文本

Micropub 请求中的自然语言内容 可以 包含双向文本。Micropub 文本值的默认基方向为从左到右。若需修改某自然语言值的基方向，可以 按如下方式操作。

如指定自然语言文本的双向属性，且首个强方向字符（参见 [BIDI]）不足以判断文本基方向，客户端 推荐 显式指定方向，可在值前加相应 Unicode 控制字符，也可对 HTML 值使用 HTML 方向标记。

支持包含双向文本的自然语言值的 Micropub 服务器 推荐 通过以下方式识别值的基方向：对纯文本，扫描首个强方向字符；HTML 值则优先用方向标记，否则扫描不在标签内的首个强方向字符。显示这些自然语言内容时，服务器 必须 按 [BIDI] 算法决定内容渲染是否需包裹额外控制字符或标签，以正确应用基方向。

3.3.5 未识别属性

如果请求中包含服务器未识别的属性，必须 忽略这些属性，并仅用已识别的属性创建文章。

这样客户端便可向支持丰富内容类型的服务器发送丰富内容，同时也能向不支持的服务器发送降级内容。

例如，客户端可创建包含体重测量的文章，weight 属性用 h-measure，summary 属性加摘要。服务器如不识别 weight 则直接忽略，仅根据 summary 创建纯文本文章。

3.3.6 响应

文章创建成功后，Micropub 端点 必须 返回 HTTP 201 Created 或 HTTP 202 Accepted 状态码，并且 必须 返回 Location 头部，指明创建内容的 URL。[RFC2616]

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。例如，可用如下响应返回一篇文章的短链：

Link: <http://aaron.pk/xxxxx>; rel="shortlink"

Link: <https://myfavoritesocialnetwork.example/aaronpk/xxxxxx>; rel="syndication"

错误响应

具体错误响应的方式见下方 "错误响应" 章节。

3.4.1 替换

替换该属性所有值。若属性不存在，则新建该属性。

{
  "action": "update",
  "url": "https://aaronpk.example/post/100",
  "replace": {
    "content": ["hello moon"]
  }
}

这样将整条内容替换为新文本，其他已存在属性不变。

3.4.2 添加

如已有属性值则保持不变，只追加新值。如无则新建该属性。

添加联合发布 URL

使用场景：文章发布后再添加联合发布链接，例如先发布后再联合到 MyFavoriteSocialNetwork 或 Wikimedia，此时需要向原文追加新的联合发布 URL。

要添加联合发布 URL，在更新请求中追加一个或多个 URL。

{
  "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"]
  }
}

添加标签

使用场景：文章已创建后补充标签。

为某属性（如 category）添加多个值，直接以数组形式提供。

{
  "action": "update",
  "url": "https://aaronpk.example/2014/06/01/9/indieweb",
  "add": {
    "category": ["micropub","indieweb"]
  }
}

3.4.3 移除

存在该属性时，将其完全移除。

{
  "action": "update",
  "url": "https://aaronpk.example/2014/06/01/9/indieweb",
  "delete": ["category"]
}

对于多值属性（如分类），可按值单独移除。当没有剩余值时该属性被完全移除。

{
  "action": "update",
  "url": "https://aaronpk.example/2014/06/01/9/indieweb",
  "delete": {
    "category": ["indieweb"]
  }
}

3.4.4 响应

服务器 必须 对成功的更新请求返回 HTTP 200、201 或 204。如果更新导致文章 URL 变更，服务器 必须 返回 HTTP 201，并在 HTTP Location 头部附上新 URL。否则应返回 200 或 204，视响应体是否含内容而定。响应体不是必须的，但 可以 包含描述变更的 JSON 对象。

3.5.1 响应

服务器必须对删除和恢复（undelete）操作的成功请求返回 HTTP 200、201 或 204。如果恢复操作导致文章 URL 发生变化，服务器必须返回 HTTP 201，并在 HTTP Location 头部包含新 URL。否则，服务器应根据响应体是否有内容返回 200 或 204。响应体可为空，但可以 包含描述本次变更的 JSON 对象。

3.6.1 发现

若 Micropub 端点支持媒体端点，服务器必须在 Micropub 配置请求返回体内用 media-endpoint 键标明媒体端点的完整 URL。客户端禁止假设媒体端点与 Micropub 端点同域。

GET /micropub?q=config
Authorization: Bearer xxxxxxxxx

{
  "media-endpoint": "https://media.example.com/micropub"
}

3.6.2 认证

媒体端点必须接受与 Micropub 端点相同的访问令牌。

3.6.3 请求

向媒体端点上传文件，客户端需用 multipart/form-data 格式 POST 请求，其中一个 part 必须命名为 file。媒体端点可以 忽略客户端建议的文件名。

multipart/form-data; boundary=553d9cee2030456a81931fb708ece92c

--553d9cee2030456a81931fb708ece92c
Content-Disposition: form-data; name="file"; filename="sunset.jpg"
Content-Type: image/jpeg
Content-Transfer-Encoding: binary

... (binary data) ...
--553d9cee2030456a81931fb708ece92c--

3.6.4 响应

媒体端点处理完文件上传，可将文件存储在任意后端，并生成该文件的 URL。推荐使用难以猜测的路径（如 UUID）。请求成功时，端点必须 在 HTTP Location 头返回文件的 URL，并响应 HTTP 201 Created。响应体内容未做规定。

HTTP/1.1 201 Created
Location: https://media.example.com/file/ff176c461dd111e6b6ba3e1d05defe78.jpg

Micropub 客户端随后可在 Micropub 请求中将此 URL 用作“photo”等属性的值。

如果媒体文件在一段时间内未被用于 Micropub 请求，媒体端点可以 定期清理、删除。

3.7.1 配置

当用户首次登录 Micropub 客户端时，客户端通常需要查询端点初始信息。客户端推荐用q=config的查询请求获取初步配置信息。

服务器推荐在配置响应中包含以下信息。

• 所支持的联合发布端点清单，属性名为 syndicate-to（具体格式参见联合发布目标部分）
• 若支持，媒体端点，属性名为 media-endpoint

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 而不是 200+空 JSON。

3.7.2 源内容

Micropub 客户端可查询端点获取文章的特定属性，从而仅请求所需或已知属性，例如搭建“为文章补加标签”界面。

支持更新文章的服务器必须支持源内容查询。

查询时，请用 GET 请求 Micropub 端点，将 q 设为 source，用 url 指明目标文章。可用 properties 指定属性名列表，多个时用数组格式，依照 [HTML5] URL 编码规则。

端点必须用 [microformats2-parsing][JSON] 格式响应，顶层为 properties 对象，键为请求属性名。若未指定属性，则响应必须返回全部属性，并含 type 属性说明词汇表类型。

GET /micropub?q=source&properties[]=published&properties[]=category&url=https://aaronpk.example/post/1000
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"
    ]
  }
}

GET /micropub?q=source&url=https://aaronpk.example/post/1000
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 键的对象返回。否则应以字符串返回，客户端视为纯文本。此行为与 [microformats2-parsing] 属性一致。

下例为请求 HTML 编辑的文章内容。

GET /micropub?q=source&properties=content&url=https://aaronpk.example/post/1000
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，值为描述所有目标的对象数组。若未定义任何联合发布目标，syndicate-to 对象值推荐为 [] 空数组。

联合发布目标对象至少必须包含 uid 和可读 name。uid 是端点唯一标识符，非用户可见。name 须清晰描述目标，供发布界面展示。

目标可以额外包含目标服务和用户详情，属性分别为 service 和 user。二者必须有 name，可以有 url 和 photo，客户端可用名称、头像美化界面。

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.7.4 查询扩展

如需扩展查询操作的功能，鼓励客户端与服务器在 indieweb.org/Micropub-extensions 头脑风暴并文档化实现。