2.1 Conformance Classes

This section describes the conformance criteria for Micropub clients and servers.

Clients

A conforming Micropub client:

• MUST support sending x-www-form-urlencoded requests for creating posts
• MUST support creating posts with the [h-entry] vocabulary
• SHOULD handle server error message gracefully, presenting helpful messages to the user
• SHOULD support endpoint discovery given an [IndieAuth] identity URL

Servers

A conforming Micropub server:

• MUST support both header and form parameter methods of authentication
• MUST support x-www-form-urlencoded requests for creating posts
• MUST support creating posts with the [h-entry] vocabulary
• SHOULD support updating and deleting posts

3.1 Overview

All Micropub requests to create posts are sent as x-www-form-urlencoded, multipart form-data [HTML5], or [JSON]-encoded HTTP requests. Responses typically do not include a response body, indicating the needed information (such as the URL of the created post) in HTTP headers. When a response body is necessary, it SHOULD be returned as a [JSON] encoded object.

3.2 Reserved Properties

A few POST body property names are reserved when requests are sent as x-www-form-urlencoded or multipart form data.

• access_token - the OAuth Bearer token authenticating the request (the access token may be sent in an HTTP Authorization header or this form parameter)
• h - used to specify the object type being created
• q - used to query a Micropub endpoint
• url - indicates the URL of the object being changed
• mp-action - indicates whether this is an update, delete, or undelete
• replace - for updates, the top-level property containing properties to replace
• add - for updates, the top-level property containing properties to add
• delete - for updates, the top-level property containing properties to remove
• mp-* - reserved for future use

When creating posts, all other properties in the request are considered properties of the object being created.

3.3 Create

To create a post, send an HTTP POST request to the Micropub endpoint indicating the type of post you are creating, as well as specifying the properties of the post. If no type is specified, the default type [h-entry] SHOULD be used. Clients and servers MUST support creating posts using the x-www-form-urlencoded encoding, and MAY also support creating posts using the JSON syntax.

h={Microformats object type}

e.g. h=entry

All parameters not beginning with "mp-" are properties of the object being created.

e.g. content=hello+world

To specify multiple values for a property, such as multiple categories of an h-entry, use array bracket notation for the property name.

e.g. category[]=foo&category[]=bar

Properties that accept multiple values MUST also accept a single value as a string. A complete example of a form-encoded request follows.

h=entry&content=hello+world&category[]=foo&category[]=bar

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--

{
  "type": ["h-entry"],
  "properties": {
    "content": ["hello world"],
    "category": ["foo","bar"]
  }
}

h=entry
&summary=Weighed+155.73+pounds
&weight[type]=h-measure
&weight[properties][num]=155.73
&weight[properties][unit]=lb
&bodyfat[type]=h-measure
&bodyfat[properties][num]=19.83
&bodyfat[properties][unit]=%

{
  "type": ["h-entry"],
  "properties": {
    "summary": [
      "Weight 155.73 pounds"
    ],
    "weight": [
      {
        "type": "h-measure",
        "properties": {
          "num": ["155.73"],
          "unit": ["lb"]
        }
      }
    ],
    "bodyfat": [
      {
        "type": "h-measure",
        "properties": {
          "num": ["19.83"],
          "unit": ["%"]
        }
      }
    ]
  }
}

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

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

3.4 Update

Micropub servers SHOULD support updating posts, including adding and removing individual properties as described in this section.

Updating entries can be done with either a JSON post or form-encoded post. The syntax of the update request is the same in both cases, using the array bracket notation when encoding in form-encoded format.

To update an entry, send mp-action=update and specify the URL of the entry that is being updated using the "url" property. The request MUST also include either a replace, add or delete property containing the updates to make.

mp-action=update
&url=http://example.com/post/1
&replace[properties][content]=hello+moon

{
  "mp-action": "update",
  "url": "http://example.com/post/1",
  "replace": {
    "properties": {
      "content": ["hello moon"]
    }
  }
}

mp-action=update
&url=http://aaronpk.example/notes/2014/06/01/2/indieweb
&add[properties][syndication][]=https://archive.org/example

{
  "mp-action": "update",
  "url": "http://aaronparecki.com/notes/2014/06/01/2/indieweb",
  "add": {
    "properties": {
      "syndication": ["https://archive.org/"]
    }
  }
}

mp-action=update
&url=http://aaronpk.example/notes/2014/06/01/2/indieweb
&add[properties][category][]=webmention
&add[properties][category][]=indieweb

{
  "mp-action": "update",
  "url": "http://aaronpk.example/notes/2014/06/01/2/indieweb",
  "add": {
    "properties": {
      "category": ["webmention","indieweb"]
    }
  }
}

mp-action=update
&url=http://example.com/post/1
&delete[properties]=category

{
  "mp-action": "update",
  "url": "http://example.com/post/1",
  "delete": {
    "properties": ["category"]
  }
}

mp-action=update
&url=http://example.com/post/1
&delete[properties][category]=indieweb

{
  "mp-action": "update",
  "url": "http://example.com/post/1",
  "delete": {
    "properties": {
      "category": ["indieweb"]
    }
  }
}

3.5 Delete

Micropub servers SHOULD support deleting posts, and MAY support undeleting posts.

To delete an entire entry at a URL, send a POST request containing mp-action=delete and the URL of the item in the url property.

mp-action=delete
&url=http://example.com/post/1

{
  "mp-action": "delete",
  "url": "http://example.com/post/1"
}

To undelete a post, use "undelete" as the action.

mp-action=undelete
&url=http://example.com/post/1

{
  "mp-action": "undelete",
  "url": "http://example.com/post/1"
}

3.6 Querying

Micropub clients may need to query the Micropub endpoint to discover its capabilities, such as finding a list of syndication targets that it displays to the user, or retrieving the source of a post to display in the updating interface.

To query, make a GET request to the Micropub endpoint and use the q parameter to specify what you are querying.

Note: The Micropub endpoint may include a query string such as ?micropub=endpoint, so in this case, Micropub clients MUST append the q parameter instead of replacing the query string.

GET /micropub?q=source&properties[]=published&properties[]=category&url=http://aaronpk.example/post/1000
Authorization: Bearer xxxxxxxxx

{
  "properties": {
    "published": ["2016-02-21T12:50:53-08:00"],
    "category": [
      "foo", 
      "bar"
    ]
  }
}

GET /micropub?q=source&url=http://aaronpk.example/post/1000
Authorization: Bearer xxxxxxxxx

{
  "type": "h-entry",
  "properties": {
    "published": ["2016-02-21T12:50:53-08:00"],
    "content": ["Hello World"],
    "category": [
      "foo", 
      "bar"
    ]
  }
}

GET /micropub?q=source&properties=content&url=http://aaronpk.example/post/1000
Authorization: Bearer xxxxxxxxx

{
  "properties": {
    "content": [
      {
        "html": "<b>Hello</b> <i>World</i>"
      }
    ]
  }
}

GET /micropub?q=syndicate-to

GET /micropub?q=syndicate-to
Authorization: Bearer xxxxxxxxx
Accept: application/json

HTTP/1.1 200 OK
Content-type: application/json

{
  "syndicate-to": [
    "https://archive.org/",
    "https://wikimedia.org/",
    "https://myfavoritesocialnetwork.example/aaronpk"
  ]
}

3.7 Error Response

If there was an error with the request, the endpoint MUST return an appropriate HTTP status code, typically 400, 401, or 403, and MAY include a description of the error. If an error body is returned, the response body MUST be encoded as a [JSON] object and include at least a single property named error with the value set to one of the below:

• HTTP 403: forbidden - The authenticated user does not have permission to perform this request
• HTTP 401: insufficient_scope - The scope of this token does not meet the requirements for this request. The client may wish to re-authorize the user to obtain the necessary scope. The response MAY include the "scope" attribute with the scope necessary to successfully perform this request.
• HTTP 400: invalid_request - The request is missing a required parameter, or there was a problem with a value of one of the parameters
• HTTP 400: not_found - The post with the requested URL was not found

The response body MAY also contain an error_description property with a human-readable description of the error message, used to assist the client developer in understanding the error. This is not meant to be shown to the end user.

See the OAuth 2 Bearer Token [RFC6750] spec for more details on the how to return error responses.

GET /micropub?q=source&url=http://aaronpk.example/post/404
Authorization: Bearer xxxxxxxx

HTTP/1.1 400 Bad Request
Content-type: application/json

{
  "error": "not_found",
  "error_description": "The post with the requested URL was not found"
}

5.1 Authentication

Micropub requests MUST be authenticated by including a Bearer Token in either the HTTP header or a form-encoded body parameter as described in the OAuth Bearer Token RFC. [RFC6750] Micropub servers MUST accept the token using both methods.

HTTP Header

Authorization: Bearer XXXXXXXXX

Form-Encoded Body Parameter

access_token=XXXXXXXXX

5.2 Authorization

An app that wants to post to a user's Micropub endpoint will need to obtain authorization from the user in order to get an access token. Authorization SHOULD be handled via the OAuth 2.0 [RFC6749] protocol, including the [IndieAuth] extension which supports endpoint discovery from a URL. See Obtaining an Access Token for more details.

5.3 Endpoint Discovery

A Micropub client SHOULD be able to be configured by authenticating with a domain name using [IndieAuth]. During this authentication (and authorization), the client discovers the Micropub endpoint which will be used to create posts.

Add a <link> tag in the HTML head of your home page, or send an HTTP Link header.

HTTP Link Header

Link: <https://example.com/micropub>; rel="micropub"

HTML Link Tag

<link rel="micropub" href="https://example.com/micropub">

5.4 Scope

The Micropub server MUST require the bearer token to include at least one scope value, in order to ensure posts cannot be created by arbitrary tokens.

The client may request one or more scopes during the authorization request. It does this according to standard OAuth 2.0 techniques, by passing a space-separated list of scope names in the authorization request. [RFC6749]

The authorization server MUST indicate to the user any scopes that are part of the request, whether or not the authorization server recognizes the scopes. The authorization server MAY also allow the user to add or remove scopes that the client requests.

Most Micropub servers require clients to obtain the "post" scope in order to create posts. However, some servers MAY require more granular scope, such as "delete", "update", or "post:video", in order to limit the abilities of various clients. See Scope for more details and a list of all currently used values for scope.