Socialwg/Social API/Micropub

From W3C Wiki

Micropub is an open API standard that is used to create posts on one's own domain using third-party clients.

Authentication

After authenticating and authorizing as a domain name, the client obtains an OAuth 2.0 access token that can be used to make requests.

The client discovers the Micropub endpoint at the domain by looking for the <link rel="micropub"> link tag, or the corresponding Link: HTTP header

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

Request Format

Micropub requests are meant to be the mirror image of Microformat posts. The most common type of request is to create an h-entry post. Requests are sent to the Micropub endpoint in form-encoded format, along with the access token in an Authorization header.

A minimal request to create a new h-entry post will look like the following:

POST /micropub HTTP/1.1
Authorization: Bearer xxxxxxxx
Content-type: application/x-www-form-urlencoded

h=entry&content=Hello+world

Examples of creating other post types can be found here: https://indiewebcamp.com/Micropub#Creating_Objects

In general, to specify other h-entry values, use the name of the field as a form-encoded parameter. For example, a blog post with a title, published date, and tags:

POST /micropub HTTP/1.1
Authorization: Bearer xxxxxxxx
Content-type: application/x-www-form-urlencoded

h=entry
&content=Hello+world
&name=Post+name
&category[]=tag1&category[]=tag2

Example repost:

POST /micropub HTTP/1.1
Authorization: Bearer xxxxxxxx
Content-type: application/x-www-form-urlencoded

h=entry
&repost-of=http://waterpigs.co.uk/notes/4S0LMw/

Example like:

POST /micropub HTTP/1.1
Authorization: Bearer xxxxxxxx
Content-type: application/x-www-form-urlencoded

h=entry
&like-of=http://waterpigs.co.uk/notes/4S0LMw/

Why Form-Encoded instead of JSON?

  • Handling form-encoded requests is easier in most environments, and handling other content types such as JSON can involve additional hurdles.
  • Supporting form-encoded requests allows a micropub form to be created in the browser.
  • There has been some discussion of supporting JSON requests since HTML JSON Forms is a w3c draft.

CRUD

The majority of Micropub clients implemented have only implemented the "create" of CRUD. We are currently brainstorming on how best to handle updates and deletes.

Current Implementations

See Also