Micropub: The Emerging API Standard for IndieWeb Apps

Twitter Client Ecosystem (2012)

• Twitter.com
• TweetDeck (Windows, OS X, iOS, Android, Browser)
• Twitterific (OS X, iOS)
• HootSuite (browser based)
• Echofon (Windows, OS X, iOS, Firefox)
• Janetter (Windows, OS X, iOS, Android)
• Tweetings (Windows, OS X)
• Destroy Twitter (Windows, OS X, Linux)
• ... many more!

Twitter Client Attribution

Micropub

• An API convention for creating and editing posts
• Based on the Microformats 2 vocabulary
• Authentication handled by OAuth 2.0 Bearer Tokens (usually obtained via IndieAuth)
• Simple form-encoded requests, with optional JSON format

Micropub Endpoint

• Will typically live within your website or CMS
• Knows how to create posts on your site
• For static sites, may be a separate server that can commit to the git repository

• Third-party app
• Needs authorization from your website
• Will eventually make a POST request to your server to create the note when you click "post"

			Application
			client_id = https://quill.p3k.io/
			redirect_uri = https://quill.p3k.io/auth/callback
			
				User
				me = https://aaronparecki.com/
			
			
				User's services
				authorization_endpoint = https://indieauth.com/auth
				token_endpoint = https://tokens.indieauth.com/token
				micropub = https://aaronparecki.com/micropub
			
		

Sign-In Form

When submitted, the server discovers the user's authorization_endpoint, and redirects the browser there with the parameters for the request.

Send the user to their auth server

https://indieauth.com/auth?me=https://aaronparecki.com/&
   client_id=https://quill.p3k.io/&
   redirect_uri=https://quill.p3k.io/auth/callback&
   state=1234567890&
   scope=post
		

Auth server presents the request

User authenticates, IndieAuth server generates an authorization code

HTTP/1.1 302 Found
Location: https://quill.p3k.io/auth/callback?
  code=xxxxxxxx&
  state=1234567890&
  me=https://aaronparecki.com/
		

Quill obtains an access token

POST https://tokens.indieauth.com/token
me=https://aaronparecki.com/&
code=xxxxxxxx&
redirect_uri=https://indiewebcamp.com/auth/callback&
client_id=https://indiewebcamp.com&
state=1234567890&
scope=post
		

Quill obtains an access token

Response:

HTTP/1.1 200 OK
me=https://aaronparecki.com/&
access_token=XXXXXX&
scope=post

Using the Access Token

• Quill can use the access token to create posts on the user's website.
• Your site needs to be able to verify access tokens
• It can query the token endpoint to check if an access token is valid

indiewebcamp.com/token-endpoint

Micropub Request

POST https://aaronparecki.com/micropub
Authorization: Bearer XXXXXXXXXXXXXXX
Content-Type: application/x-www-form-urlencoded

h=entry&
content=Hello+World
		

Micropub Response

HTTP/1.1 201 Created
Content-Type: application/x-www-form-urlencoded
Location: http://aaronparecki.com/notes/2014/06/23/1/
Link: <http://aaron.pk/n4Wj1> rel="shortlink"
		

Post with Location

POST https://aaronparecki.com/micropub
Authorization: Bearer XXXXXXXXXXXXXXX
Content-Type: application/x-www-form-urlencoded

h=entry&
content=Hello+World
location=geo:45.525185,-122.681633
		

A "like" post

POST https://aaronparecki.com/micropub
Authorization: Bearer XXXXXXXXXXXXXXX
Content-Type: application/x-www-form-urlencoded

h=entry&
like-of=http://example.com/thing/that/is/liked
		

Even more kinds of posts

• Vocabulary is from Microformats2
• http://indiewebcamp.com/h-entry
• http://microformats.org/wiki/h-entry

Micropub

• Why form-encoded and multipart first?
• All server-side environments support form-encoded requests
• Provides a built-in method of attaching files and other content
• Easiest for publishers and consumers to parse

Editing with Micropub

• How to support editing or partial edits?
• Creating is a simple POST request
• What is the easiest way to handle edits?

Note: Still in progress

• Many implementations of Micropub servers for creating
• Very few implementations for editing

Microformats 2

<div class="h-entry">
  <p class="p-name e-content">Hello World</p>
  <a class="p-author h-card" href="http://aaronpk.com">
    Aaron Parecki
  </a>
  <a href="http://aaronpk.com/post/1" class="u-url">
    <time class="dt-published" datetime="2015-06-24">
      June 24, 2015
    </time>
  </a> 
</div>
		

{
  "items": [{
    "type": ["h-entry"],
    "properties": {
      "author": [{
        "type": ["h-card"],
        "properties": {
          "name": ["Aaron Parecki"],
          "url": ["http:\/\/aaronpk.com"]
        },
        "value": "Aaron Parecki"
      }],
      "name": ["Hello World"],
      "published": ["2015-06-24"],
      "url": ["http:\/\/aaronpk.com\/post\/1"],
      "content": ["Hello World"]
    }
  }]
}

Edits as their own posts

Like pull requests on GitHub

• Syntax derived from creating a Microformats2 post describing the edit

Replacing a property

{
  "edit-of": "http://example.com/post/1",
  "update": {
    "properties": {
      "content": ["hello moon"]
    }
  }
}

Adding a value to a property

{
  "edit-of": "http://example.com/post/1",
  "add": {
    "properties": {
      "category": ["indieweb","foo"]
    }
  }
}

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.

Removing a value from a property

{
  "edit-of": "http://example.com/post/1",
  "delete": {
    "properties": {
      "category": ["indieweb"]
    }
  }
}

This removes just the "indieweb" value from the "category" property, leaving all other values. If no values remain, the property is removed.

Removing a property completely

{
  "edit-of": "http://example.com/post/1",
  "delete": {
    "properties": ["category"]
  }
}

Deleting a post

{
  "delete-of": "http://example.com/post/1"
}