Micropub-extensions

From IndieWeb
Jump to: navigation, search

This page is for documenting extensions to Micropub.

Discussion on GitHub

Server Commands

The Micropub spec reserves the mp- prefix in the form-encoded syntax as a mechanism for clients to give commands to servers. This section is for brainstorming additional uses of the mp- functionality.

Slug

Issues and discussion:
https://github.com/indieweb/micropub-extensions/projects/1

Many posting UIs provide an option for the user to choose a slug for the post that will be created.

wordpress-customize-slug.png

This proposal is for a new mp- command for the client to suggest a slug to the Micropub endpoint.

  • mp-slug=

The server may or may not decide to respect the requested slug, based on whether it would cause conflicts with other URLs on the site. For example, some URL structures are {year}/{slug}, so the server may decide to modify the slug to avoid conflicting with an existing one.

Implementations

Destination

Issues and discussion:
https://github.com/indieweb/micropub-extensions/projects/4

Specify a destination to create a new post on a web site other than the default. The value of mp-destination should be a uid from the array of destinations returned from q=config. See an example query response here.

Implementations

  • Clients
    • Monocle - Monocle will check if your Micropub server returns a list of destinations and will then provide an account chooser UI in the footer when viewing a timeline. Selecting an account will cause any of the response buttons to be sent with the corresponding mp-destination value.
  • Servers

New Properties

Post Status

Issues and discussion:
https://github.com/indieweb/micropub-extensions/projects/2
  • post-status=published (or no post-status set) - The post is published, or when the published date is in the future, the post is scheduled.
  • post-status=draft - The post is a draft, and should not be shown in lists. (Of course it's up to the implementation whether it wants to use a capability URL for draft posts or actually restrict it to logged-in users.)

Implementations

Visibility

Issues and discussion:
https://github.com/indieweb/micropub-extensions/projects/3
  • visibility=public (or no visibility set)
  • visibility=private

In addition to public/private visibility, Wordpress also supports password-protected posts. However, passwords are inherently insecure and also not very user friendly, and there are likely better solutions to the problem. Essentially the goal of password-protected posts on Wordpress is to provide "guest access" to posts, where the viewer does not need an account at the site. Flickr accomplishes this with something they call "guest passes".

As well as public or private there could also be use in a value to hide posts from a main feed. Grant Richmond uses visibility=unlisted for this with his photo posts that appear in a gallery collection - The photos have their own post with a unique viewable url, but appear in a gallery post in the main feed, not as multiple individual photos. "unlisted" is already in use by mastodon.

Implementations

Location Visibility

Proposal by David Shanske

  • location-visibility=public (or no visibility set)
  • location-visibility=private
  • location-visibility=protected

This is based on David Shanske's implementation in Simple Location, an Indieweb friendly location plugin, of the WordPress Geodata unofficial guidelines. It states a single property which can be set to public or private, with the absence of the property being considered to be public. Proposing the third property, which will allow for a less specific text only display, but no actual coordinates.

Implementations

Query

Micropub supports making a GET request to a Micropub endpoint with a q= parameter, in order to query aspects of the endpoint or for retrieving the original source content of posts. This section is for brainstorming additional uses of the query functionality. See also Micropub-brainstorming#Query_for_other_information

Query for Supported Vocabulary

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/1

This is an extension for returning what properties a Micropub server supports, so that a client like Quill or Indigenous could know to hide or rename the common choices in the UI. This is essentially using reverse [Post Type Discovery]. The following example would be returned as part of the ?q=config query

  "post-types": [
    {
      "type": "note",
      "name": "Note"
    },
    {
      "type": "article",
      "name": "Blog Post"
    },
    {
      "type": "photo",
      "name": "Photo"
    },
    {
      "type": "video",
      "name": "Video"
    },
    {
      "type": "reply",
      "name": "Reply"
    },
    {
      "type": "like",
      "name": "Like"
    },
    {
      "type": "repost",
      "name": "Repost"
    },
    {
      "type": "rsvp",
      "name": "RSVP"
    },
    {
      "type": "bookmark",
      "name": "Bookmark"
    }
  ]

Implementations

Query for Post List

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/4

This is a possible extension to the q=source query on my micropub endpoint, if no url is provided it returns a list of posts. This makes the url part of the query really into more of a filter. This would be super handy for clients wanting to present a list of posts to edit/delete/undelete.

Another advantage of this extension is that your micropub server is just responsible for storing and listing posts as microformats, rendering posts can be another bit of software's responsibility

{
 "items": [
  {
    "type": [
      "h-entry"
    ],
    "properties": {
      "like-of": [
        "https:\/\/en.m.wikipedia.org\/wiki\/Poka-yoke"
      ],
      "uid": [
        "20170820131258_59998adae54d0"
      ],
      "published": [
        "2017-08-20T13:12:58+00:00"
      ]
    }
  },
  {
    "type": [
      "h-entry"
    ],
    "properties": {
      "photo": [
        "https:\/\/media.j4y.co\/2017\/cfd007ec-c819-47da-99a2-daec2e91a41e.jpg"
      ],
      "published": [
        "2017-08-19T18:30:40+00:00"
      ],
      "content": [
        ""
      ],
      "category": [
        ""
      ],
      "uid": [
        "20170819175715_59987bfb72c4f"
      ]
    }
  }
}

Implementations

Query for Category/Tag List

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/5

This is an extension for returning categories that a Micropub server has received in the past, so that a client like Quill or Indigenous could present a list of existing categories to choose from when creating a new post. This also incorporates the possibility of being able to search for categories that would match an auto-complete.

The following example would be returned as part of the ?q=category query.

{
  "categories": [
    "tag1",
    "tag2",
    "tag3",
    "tag4",
    "tag5",
  ]
}

The follow example would be returned as part of the ?q=category&search=indie query.

{
  "categories": [
    "indieweb",
    "indieweb-goals",
    "indienews"
  ]
}

Implementations

Brainstorming

category - suggestion to get all existing tags/categories in the client. Expectation is client would cache and do autocomplete


Query for Supported Properties/Queries

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/7
https://github.com/indieweb/micropub-extensions/issues/8

These are two extensions for returning queries that a Micropub server will respond to and properties that a server knows about, so that a client like Quill or Indigenous could present only options appropriate to that server. It is similar to the idea about querying for supported vocabulary, except that proposal only covers properties that are part of post-type discovery. Like with the other proposal, the absence of this instruction would show everything.

The following example would be returned as part of the ?q=config query for supported queries.

{
  "q": [
    "config",
    "syndicate-to",
    "category",
    "source",
    "geo",
  ]
}

The following would be returned as part of the ?q=config query for supported experimental properties unrelated to post-types. These are experimental properties that would require a field within the UI.

{
  "properties": [
    "location-visibility",
    "visibility",
    "post-status",
  ]
}

Implementations


Query for Location/Venue

Issues and discussion:
https://github.com/indieweb/micropub-extensions/issues/6

Jonny Barnes originally added Query for Places in 2015. His implementation was for /micopub?q=geo=lat.lng;u=XX, returning a JSON response for each place containing a display name, lat/lng value, and a URL that could be used as the location value in a subsequent request.

David Shanske expanded on that to be consistent with the current thinking that returns should be inside a property and to allow for a geo URI or the individual parameters. The geo=lat.lng;u=xx is close to the geo URI format of geo:37.786971,-122.399677;u=35 but in the interest of consistency should actually be a GEO URI and a separate property. Therefore, the query for a request with a Geo URI should be ?q=geo&uri=geo:37.786971,-122.399677;u=35 or optionally, each variable individually... q=geo&lat=x&lon=y&u=z

The following example would be returned as part of the ?q=geo&lat=x&lon=y query. Return would contain two properties, 'venues' and 'geo'. Geo would be a suggestion for the queried location perhaps returned using reverse geolocation, and venues would be one or more venues. The lack of either property assumes nothing could be found about the location.

All returns would follow the common properties of an h-adr object with only label and latitude/longitude being mandatory. There is one optional extra parameter, following the proposed Location Visibility property which would allow the query to suggest whether this location should be publicly displayed, allowing for private venues.

{
  "geo": [
    "label" : "123 Main Street",
    "latitude": "18.1123",
    "longitude": "-72.1933",
    "visibility": "public",
  ],
  "venues": [
   { 
     "label" : "Main Street Apothecary",
     "latitude": "18.1123",
     "longitude": "-72.1931",
     "url": "https://example.com/venues/apothecary",
   },
   { 
     "label" : "Main Street Market",
     "latitude": "18.1123",
     "longitude": "-72.1931",
     "url": "https://example.com/venues/market",
   },
  ]
}

Implementations

Brainstorming

Ideas for other types of queries

  • mp-config
  • extended markup formats – right now it is relatively dependent on the server implementation how text content is treated (1:1, basic processing like linking URLs, Markdown, ...). A query could expose information about this (and maybe even be part of a way to choose for the user)
  • media endpoint history – query recent uploads to the media endpoint, e.g. the last X photos uploaded from a phone

Questions

  • According to the current spec (2017-01), a GET ?q=config should also include the syndicate-to property. If the collection of supported properties grows, is this still a thing to hold on to? Venues and tags can make the response potentially large. Sebastiaan Andeweg
    • Agreed, I think the empty GET ?q=config should be very limited, and clients should reqest things with potentially large responses separately. Aaron Parecki 11:40, 11 April 2018 (PDT)

Location checkin information

Indigenous for Android has a checkin post type which passes the checkin information as additional parameters in the Geo URI. The payload property is 'checkin'. It's not doing a JSON post, so you can also immediately upload pictures as well. Additional properties for the venue/location can be added later. The same technique is used to post my geocache logs, see https://indieweb.org/geocaching

geo:51.5258325,-0.1359825,0.0;name=london;url=https://hwclondon.co.uk

This is supported by the Drupal IndieWeb module. An example can be found here: https://realize.be/checkin/1762

See Also