Socialwg/Social API/Micropub
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
- 8+ different client implementations that interoperate with
- 6+ different server implementations
See Also
- Micropub on indiewebcamp.com
- Creating a Micropub Endpoint tutorial