2.1.1 Publishing Clients

A conforming Micropub client that creates posts:

• MUST support sending x-www-form-urlencoded requests
• MUST support the [h-entry] vocabulary
• If the client creates posts by uploading file attachments, it MUST check for the presence of a Media Endpoint and if present, send the file there instead of to the Micropub endpoint
• SHOULD handle server error messages gracefully, presenting helpful messages to the user
• SHOULD support endpoint discovery

2.1.2 Editing Clients

A conforming Micropub client that edits posts:

• MUST support sending JSON-encoded requests
• MUST support the [h-entry] vocabulary

2.1.3 Servers

A conforming Micropub server:

• MUST support both header and form parameter methods of authentication
• MUST support creating posts with the [h-entry] vocabulary
• SHOULD support updating and deleting posts
• If the server does not specify a Media Endpoint, then it MUST support x-www-form-urlencoded requests for creating posts

2.2.1 Client

A Micropub Client is an implementation that sends Micropub requests to create or otherwise manipulate posts. The conformance criteria are described in Conformance Classes above.

2.2.2 Server

A Micropub Server is an implementation that can create and optionally edit and delete posts given a Micropub request. The Micropub server MAY also support a Media Endpoint for handling file uploads outside of the primary Micropub endpoint. The conformance criteria are described in Conformance Classes above.

2.2.3 Independent

Each implementation must be developed by a different party and cannot share, reuse, or derive from code used by another qualifying implementation. Sections of code that have no bearing on the implementation of this specification are exempt from this requirement.

2.2.4 Interoperable

A Client and Server implementation are considered interoperable for a specific feature when the Server takes the defined action that the Client requests, the Client gets the expected response from a Server according to the feature, and the Server sends the expected response to the Client.

2.2.5 Implementation

An Implementation is a Micropub Client or Server which meets all of the following criteria:

• implements the corresponding conformance class of the specification
• is available to the general public, as downloadable software or as a hosted service
• is not experimental (i.e. is intended for a wide audience and could be used on a daily basis)
• is suitable for a person to use as his/her primary implementation on a website

2.2.6 Feature

For the purposes of evaluating exit criteria, each of the following is considered a feature:

• Discovering the Micropub endpoint given the profile URL of a user
• Authenticating requests by including the access token in the HTTP Authorization header
• Authenticating requests by including the access token in the post body for x-www-form-urlencoded requests
• Limiting the ability to create posts given an access token by requiring that the access token contain at least one OAuth 2.0 scope value
• Creating a post using x-www-form-urlencoded syntax with one or more properties
• Creating a post using JSON syntax with one or more properties
• Creating a post using x-www-form-urlencoded syntax with multiple values of the same property name
• Creating a post using JSON syntax with multiple values of the same property name
• Creating a post using x-www-form-urlencoded syntax including a nested Microformats2 object
• Creating a post using JSON syntax including a nested Microformats2 object
• Uploading a file to the specified Media Endpoint
• Creating a post with a file by sending the request as multipart/form-data to the Micropub endpoint
• Returning HTTP 201 Created and a Location header when creating a post
• Returning HTTP 202 Created and a Location header when creating a post
• Updating a post and replacing all values of a property
• Updating a post and adding a value to a property
• Updating a post and removing a value from a property
• Returning HTTP 200 OK when updating a post
• Returning HTTP 201 Created when updating a post if the update cause the post URL to change
• Returning HTTP 204 No Content when updating a post
• Deleting a post using x-www-form-urlencoded syntax
• Deleting a post using JSON syntax
• Undeleting a post using x-www-form-urlencoded syntax
• Undeleting a post using JSON syntax
• Uploading a photo to the Media Endpoint and using the resulting URL when creating a post
• Querying the Micropub endpoint with q=config to retrieve the Media Endpoint and syndication targets if specified
• Querying the Micropub endpoint with q=syndicate-to to retrieve the list of syndication targets
• Querying the Micropub endpoint for a post's source content without specifying a list of properties
• Querying the Micropub endpoint for a post's source content looking only for specific properties

3.3.1 Uploading Files

To upload files, the client MUST check for the presence of a Media Endpoint. If there is no Media Endpoint, the client can assume that the Micropub endpoint accepts files directly, and can send the request to it directly, To upload a file to the Micropub endpoint, format the whole request as multipart/form-data and send the file(s) as a standard property.

For example, to upload a photo with a caption, send a request that contains three parts, named h, content and 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--

For properties that can accept a file upload (such as photo or video), the Micropub endpoint MUST also accept a URL value, treating that the same as if the file had been uploaded directly. The endpoint MAY download [Fetch] a copy of the file at the URL and store it the same way it would store the file if it had been uploaded directly. For example:

h=entry&content=hello+world&photo=https://photos.example.com/592829482876343254.jpg

This is to support uploading files via a Media Endpoint, or by reference to other external images. See the Media Endpoint section for more information.

3.3.2 JSON Syntax

Alternately, you can create a post with JSON syntax by sending the entry in the parsed Microformats 2 JSON format.

Note that in this case, you cannot also upload a file, you can only reference files by URL as described above.

When creating posts in JSON format, all values MUST be specified as arrays, identical to the Microformats 2 JSON format.

{
  "type": ["h-entry"],
  "properties": {
    "content": ["hello world"],
    "category": ["foo","bar"],
    "photo": ["https://photos.example.com/592829482876343254.jpg"]
  }
}

3.3.3 Nested Microformats Objects

Whenever possible, nested Microformats objects should be avoided. A better alternative is to reference objects by their URLs. The most common example is including an h-card for a venue, such as checking in to a location or tagging a photo with a person or location. In these cases, it is better to reference the object by URL, creating it first if necessary.

This technique has the advantage of ensuring that each object that is created has its own URL (each piece of data has its own link). This also gives the server an opportunity to handle each entity separately. E.g., rather than creating a duplicate of an existing venue, it may give back a link to one that was already created, possibly even merging newly received data first.

In some cases, it does not make sense for the nested object to have a URL. For example, when posting an h-measure value, there is no reason for the h-measure itself to have a URL, so this is an acceptable case to use the nested Microformats object syntax.

The example below creates a new "weight" measurement post as an h-entry with a h-measure objects to describe the weight and bodyfat values.

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": ["%"]
        }
      }
    ]
  }
}

3.3.4 Unrecognized Properties

If the request includes properties that the server does not recognize, it SHOULD create the post anyway with any values that are recognized, and SHOULD store the unrecognized values internally, and return them when queried.

This allows clients to post rich types of content to servers that recognize it, while also posting fallback content to servers that don't.

3.3.5 Response

When the post is created, the Micropub endpoint MUST return either an HTTP 201 Created status code or HTTP 202 Accepted code, and MUST return a Location header indicating the URL of the created post. [RFC2616]

HTTP/1.1 201 Created
Location: https://aaronpk.example/post/1000

If the endpoint chooses to process the request asynchronously rather than creating and storing the post immediately, it MUST return an HTTP 202 Accepted status code, and MUST also return the Location header in this case. If the server is going to return 202, it MUST ensure the object will be created successfully prior to returning 202, as clients will expect the object at the indicated URL to exist at some point in the (near) future. In other words, the server must do any error checking and validation before returning 202.

If the target also provides a shortlink, or if it syndicated the post to another location, the Micropub endpoint MAY return additional URLs using the HTTP Link header, along with an appropriate "rel" value. For example, it can return the short URL of a post by responding with:

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

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

Error Response

See the "Error Responses" section below for details on how to indicate an error occurred.

3.4.1 Replace

Replace all values of the property. If the property does not exist already, it is created.

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

This will replace the entire entry content with the new text.

3.4.2 Add

If there are any existing values for this property, they are not changed, the new values are added. If the property does not exist already, it is created.

Adding a syndication URL

Use case: adding a syndication link to a post after it has been published. For example, when a client supports posting first then syndicating to MyFavoriteSocialNetwork or Wikimedia after the fact, the site needs a way to update the original post with the new syndication URL.

To add syndication URLs, include one or more URLs in the update request.

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

Adding Tags

Use case: adding tags to a post after it's been created.

To add multiple values to a property (such as category), provide the new values in an array.

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

3.4.3 Remove

If the property exists, remove it. This completely removes the specified property.

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

For properties with multiple values, such as categories, you can remove individual entries by value. If no values remain, the property is removed.

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

3.4.4 Response

The server MUST respond to successful update requests with HTTP 200, 201 or 204. If the update operation caused the URL of the post to change, the server MUST respond with HTTP 201 and include the new URL in the HTTP Location header. Otherwise, the server MUST respond with 200 or 204, depending on whether the response body has content. No body is required in the response, but the response MAY contain a JSON object describing the changes that were made.

3.6.1 Discovery

To advertise that the Micropub endpoint supports a Media Endpoint, the server MUST include a key called media-endpoint with a value of the full URL of the Media Endpoint in the Micropub configuration request. Clients MUST NOT assume the Media Endpoint is on the same domain as the Micropub endpoint.

GET /micropub?q=config
Authorization: Bearer xxxxxxxxx

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

3.6.2 Authentication

The Media Endpoint MUST accept the same access tokens that the Micropub endpoint accepts.

3.6.3 Request

To upload a file to the Media Endpoint, the client sends a multipart/form-data request with one part named file. The Media Endpoint MAY ignore the suggested filename that the client sends.

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 Response

The Media Endpoint processes the file upload, storing it in whatever backend it wishes, and generates a URL to the file. The URL SHOULD be unguessable, such as using a UUID in the path. If the request is successful, the endpoint MUST return the URL to the file that was created in the HTTP Location header, and respond with HTTP 201 Created. The response body is left undefined.

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

The Micropub client can then use this URL as the value of e.g. the "photo" property of a Micropub request.

The Media Endpoint MAY periodically delete files uploaded if they are not used in a Micropub request within a specific amount of time.

3.7.1 Configuration

When a user initially logs in to a Micropub client, the client will want to query some initial information about the user's endpoint. The client SHOULD make a query request q=config to obtain initial configuration information.

The server SHOULD include the following information in the configuration response.

• The list of syndication endpoints supported (see Syndication Targets for details)
• The Media Endpoint if supported

GET /micropub?q=config
Authorization: Bearer xxxxxxxxx

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

3.7.2 Source Content

A Micropub client can query the endpoint to return specific properties of a post. This allows a client to request only the properties it needs or knows about, supporting such uses as making an interface to add tags to a post.

To query, make a GET request to the Micropub endpoint and set the q parameter to source, and include the URL of the post in the url parameter. The query can specify the list of properties being requested by setting one or more values for the properties key. If more than one is specified, use array bracket notation for each name, according to [HTML5] URL encoding.

The endpoint MUST return the response in [microformats2-parsing] [JSON] format, with an object named properties, where the keys are the names of the properties requested. If no properties are specified, then the response MUST include all properties, as well as a type property indicating the vocabulary of the post.

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

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

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

HTML Content

If the source of the post was written as HTML content, then the endpoint MUST return the content property as an object containing an html property. Otherwise, the endpoint MUST return a string value for the content property, and the client will treat the value as plain text. This matches the behavior of the values of properties in [microformats2-parsing].

Below is an example of requesting the content of a post which was authored as HTML.

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

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

3.7.3 Syndication Targets

To return a list of supported syndication targets, set the q parameter to syndicate-to.

GET /micropub?q=syndicate-to

The endpoint MUST return the response in [JSON] format, with a key of syndicate-to and the values being objects descriptive of the supported syndication targets.

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