Micropub

De Mi caja de notas

Révision datée du 8 avril 2018 à 16:24 par Xtof (discussion | contributions) (→‎Aperçu)

Micropub est un standard d'API ouvert (Recommandation W3C) qui est utilisé pour créer, mettre à jour et effacer des posts son propre domaine en utilisant des clients tiers, et remplace à la fois MetaWeblog et AtomPub. Les web apps et apps natives (comme iPhone, Android) peuvent utiliser Micropub pour poster et modifier des articles, des notes courtes, des commentaires, des likes, des photos, des événementss, ou d'autres types de posts sur votre propre site.

(new!) Submit an implementation report for Micropub to help the specification advance at W3C!

W3c-spec-REC.svg


Contexte

Le vocabulaire Micropub est dérivé directement du vocabulaire Microformats. Micropub est censé être une sérialisation de Microformats qui peuvent être soumis en tant que HTTP POST. La méthode pour développer de nouveaux vocabulaires Micropub est de regarder la représentation Microformats et de revenir en arrière.

Syntaxe

Similaire à la façon dont microformats a un jeu de règles relativement petit pour analyser les documents HTML dans une structure de données, Micropub définit un petit ensemble de règles pour interpréter les requêtes HTTP POST et GET en tant que commandes Micropub. Là où les Microformats ne nécessitent pas de modifier les règles d'analyse pour introduire de nouvelles propriétés d'un objet tel qu'une entrée h, Micropub ne nécessite pas non plus de modifier les règles d'analyse pour interpréter les requêtes qui correspondent à différents types de publication, par exemple poster des vidéos vs "j'aime"


La syntaxe Micropub décrit comment interpréter les requêtes HTTP POST et GET en une action utile que le serveur peut prendre.

La spécification peut être lue sur https://www.w3.org/TR/micropub/

Aperçu

Toutes les requêtes Micropub pour créer des messages sont envoyées sous la forme de formulaires encodés[1], multipart formulaire-data [2], ou de requêtes HTTP codées en JSON. Les réponses n'incluent généralement pas de corps de réponse, indiquant les informations nécessaires (telle que l'URL de la publication créée) dans les en-têtes HTTP. Lorsqu'un corps de réponse est requis, il est renvoyé sous la forme d'un codage de formulaire ou JSON [3], en fonction de HTTP Accept /rfc7231#section-5.3.2 en-tête.

Comment implémenter

How to implement the Micropub API, both in a client that can discover an endpoint and publish to it, and on a server to support an endpoint to create/update/delete posts in response.

Découverte du Endpoint

It should be possible to configure an API client by authenticating as your domain name using IndieAuth. After signing in, your domain needs a way to specify the API endpoint the client will use to create new posts.

Add a <link> tag in the HTML head of your home page, or send an HTTP Link header.

HTTP Header

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

HTML Head

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

Authentication

Micropub requests are authenticated by including a Bearer Token in either the HTTP header or a form-encoded body parameter as described in the OAuth Bearer Token RFC.

Authorization should be handled via the IndieAuth protocol, built on top of OAuth 2.0. See obtaining-an-access-token for more details. An app that wants to post to a user's Micropub endpoint will need to obtain authorization from the user in order to get an access token.

HTTP Header

Authorization: Bearer XXXXXXXX

Form-Encoded Body Parameter

access_token=XXXXXXXXX

Scope

The client may request one or more scopes during the authorization request. It does this according to standard OAuth 2.0 techniques, by passing a space-separated list of scope names in the authorization request.

The authorization server must indicate to the user any scopes that are part of the request, whether or not the authorization server recognizes the scopes. The authorization server may also allow the user to add or remove scopes that the client requests.

For example, most Micropub servers require clients to obtain the "create" scope in order to create posts. (The legacy "post" scope previously encompassed both creating and updating posts.) However, some servers may require more granular scope requests, such as "delete" or "create:video". See scope for more details and a list of all currently used values for scope.

Verification

A micropub client can verify that an access token is still valid (and other details) by querying the user's token endpoint.

Issues:

  • this does not cover the case where the server has decided not to accept it anymore, e.g. because the user's access to the site has been removed
    • if a micropub endpoint plans on rejecting a token in the future, it should ensure the token endpoint also rejects the token. For systems where the token endpoint and micropub endpoint are part of the same software, this is an implementation detail. If the token endpoint and micropub endpoint are on different systems, there needs to be a mechanism for the micropub endpoint to expire the token at the token endpoint. This is what's known as token revocation, and has been written up for OAuth 2: https://tools.ietf.org/html/rfc7009

Form-encoded Microformats Representation

For the simplicity of writing clients and servers, all Micropub endpoints must handle the standard form-encoded format. At a most basic level, you should be able to write an HTML form and set the form action to your own endpoint and use it to post to your site.


Examples of Creating Objects

How to create some of the common post types

Indicating the object being created

To indicate the object being created, use a property called "h", (which would never be the name of a property of a microformats object), followed by the name of the microformats object. Examples:

  • h=entry
  • h=card
  • h=event
  • h=cite

h-entry

The following properties may be included in a request to create a new h-entry:

  • name
  • summary
  • content
  • published
  • updated
  • category = tag1, tag2, tag3 (sent as array syntax: &category[]=tag1&category[]=tag2)
  • location
  • in-reply-to
  • repost-of
  • syndication
    • Pass one or more URLs pointing to places where this entry already exists. Can be used for PESOS implementations.
  • mp-syndicate-to = https://myfavoritesocialnetwork.example/aaronpk, https://archive.org/, etc.
    • This property is slightly different from the others since it is giving a command to the server rather than describing an object, which is why it is prefixed with "mp-".
Nouvelle Note

Posting a new note with tags, syndicating to myfavoritesocialnetwork:

  • content
  • category
  • mp-syndicate-to
  • published (optional, defaults to "now" if not present. Useful for writing offline and syncing later)
POST /micropub HTTP/1.1
Host: aaronparecki.com
Content-type: application/x-www-form-urlencoded

h=entry
&content=The+%40Jawbone+UP%2C+my+favorite+of+the+%23quantifiedself+trackers%2C+finally+released+their+official+API%21+http%3A%2F%2Fjawbone.com%2Fup%2Fdeveloper%2F
&category[]=jawbone&category[]=quantifiedself&category[]=api
&mp-syndicate-to=https://myfavoritesocialnetwork.example/aaronpk
Exemple minimal
POST /micropub HTTP/1.1
Host: example.com
Content-type: application/x-www-form-urlencoded
Authorization: Bearer XXXXXXX

h=entry
&content=Hello+World

curl https://example.com/micropub -d h=entry -d "content=Hello World" -H "Authorization: Bearer XXXXXXX"
Nouvelle Réponse

Posting a new reply, syndicating to myfavoritesocialnetwork

  • content
  • in-reply-to
  • mp-syndicate-to
  • published
POST /post/new HTTP/1.1
Host: aaronparecki.com
Content-type: application/x-www-form-urlencoded

h=entry
&content=%40BarnabyWalters+My+favorite+for+that+use+case+is+Redis.+It%27s+easy+to+set+up+and+use%2C+I+often+use+it+to+move+data+between+apps+written+in+different+languages+too.
&in-reply-to=http://waterpigs.co.uk/notes/4S0LMw/
&mp-syndicate-to=https://myfavoritesocialnetwork.example/aaronpk
Nouveau Repost

Posting a new repost, and adding additional tags.

  • repost-of
  • category
POST /micropub HTTP/1.1
Host: aaronparecki.com
Content-type: application/x-www-form-urlencoded

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

Posting a new article

  • content
  • name
  • category
  • published
POST /micropub HTTP/1.1
Host: aaronparecki.com
Content-type: application/x-www-form-urlencoded

h=entry
&content=Now+that+I%27ve+been+%5Bhttp%3A%2F%2Faaronparecki.com%2Fevents+creating+a+list+of+events%5D+on+my+site+using+%5Bhttp%3A%2F%2Findiewebcamp.com%2Fp3k+p3k%5D%2C+it+would+be+great+if+I+could+get+a+more+calendar-like+view+of+that+list.+%0A%0ASince+I+live+in+Google+Calendar+every+day+anyway%2C+it+would+be+great+to+use+that+interface+to+browse+my+%23indieweb+events+as+well%21+Since+my+events+page+is+marked+up+with+%5Bhttp%3A%2F%2Fmicroformats.org%2Fwiki%2Fh-event+h-event+microformats%5D%2C+all+it+would+take+is+to+write+an+h-event+to+iCal+converter+script+to+generate+an+iCal+feed+from+my+list+of+events.+Then+I+could+just+subscribe+to+the+iCal+feed+from+within+Google+Calendar.%0A%0A%23%23%23+Bonus%3A+read%2Fwrite+access+to+indieweb+events+via+Google+Calendar%0A%0AEven+better+would+be+to+use+Google+Calendar+to+also+create+events+on+my+site.+Unfortunately+Google+Calendar+doesn%27t+support+CalDAV%2C+so+we+can%27t+do+it+that+way.+%28Of+course+I+could+use+Apple%27s+iCal+to+publish+directly%2C+but+that+also+means+I%27d+have+to+write+some+code+tot+speak+CalDAV%29.+%0A%0AInstead%2C+I+can+create+a+%22write-only%22+calendar+in+Google+Calendar%2C+and+have+p3k+subscribe+to+it.+Any+new+events+in+that+feed+would+be+moved+over+to+the+internal+events+page+and+deleted+from+the+Google+Calendar.
&name=Itching%3A+h-event+to+iCal+converter
&category[]=indieweb&category[]=hevent&category[]=events&category[]=calendar&category[]=p3k
Nouveau Signet

Posting a new bookmark with name, quote, and tags.

  • bookmark-of
  • name
  • content
  • category
POST /micropub HTTP/1.1
Host: aaronparecki.com
Content-type: application/x-www-form-urlencoded

h=entry
&bookmark-of=https%3A%2F%2Fplus.google.com%2F%2BKartikPrabhu%2Fposts%2FUzKErSbfmHq
&name=To+everyone+who+is+complaining+about+Popular+Science+shutting+down+comments...
&content=%22Why+is+there+this+expectation+that+every+website+should+be+a+forum%3F+No+website+has+any+obligation+to+provide+a+space+for+your+rants.+Use+your+own+space+on+the+web+to+do+that.%22
&category[]=indieweb&category[]=comments


Ajouter des Fichiers

When a Micropub request includes a file, the entire request is sent in the multipart/form-data encoding, and the file is named by content type, either "audio", "video" or "photo". A request may include one or more of these files.

When OwnYourGram makes a Micropub request to post a video, it also sends a photo which is a thumbnail preview of the video.

In PHP, these files are accessible using the $_FILES array: 

$_FILES['video']
$_FILES['photo']
$_FILES['audio']

see also: Micropub-brainstorming#Uploading_files_in_separate_requests

Note that there is no practical way to upload a file when the request body is JSON encoded. The media endpoint needs to be used in that case.

curl example: 

$ curl -H 'Authorization: Bearer abc'\
       -F 'h=entry'\
       -F 'content=an image!'\
       -F 'photo=@/home/cweiske/Bilder/openid-id.bogo.png'\
       'http://known.bogo/micropub/endpoint'

h-event

The following properties may be included in a request to create a new h-event:

Posting a new event

  • name
  • summary
  • description
  • start
  • end
  • duration
  • category
  • location
POST /micropub HTTP/1.1
Host: aaronparecki.com
Content-type: application/x-www-form-urlencoded

h=event
&name=IndieWeb Dinner at 21st Amendment
&description=In SF Monday evening? Join @caseorganic and I for an #indieweb dinner at 6pm! (Sorry for the short notice!)
&start=2013-09-30T18:00:00-07:00
&category=indieweb
&location=http://21st-amendment.com/


h-cite

The following properties may be included in a request to create a new h-cite:

(The following list is from microformats.org/wiki/h-cite)

  • name
  • published - date of publication of the work (not the date the h-cite was created)
  • author - URL of an h-card
  • url - a URL to access the cited work
  • content - the content or partial content of the work itself, such as when including a blockquote snippet of a work

Objets Microformats Embarqués

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.

For simple values such as an h-geo property with latitude and longitude, just use a Geo URI such as geo:37.786971,-122.399677

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 in newly received data first.

For more complicated objects, it is better to first create an object on the target site so that it has its own URL, then reference that object's URL in the main request.

For example, creating a checkin post would involve two POST requests:

First create the venue by posting an h-card: 

POST /micropub

h=card
&name=Ford+Food+and+Drink
&url=http://www.fordfoodanddrink.com/
&street-address=2505 SE 11th Ave
&locality=Portland
&region=OR
&postal-code=97214
&geo=geo:45.5048473,-122.6549551
&tel=(503) 236-3023

Response: 

HTTP/1.1 201 Created
Location: http://example.com/venue/10

Then create the checkin post: 

POST /micropub

h=entry
&location=http://example.com/venue/10
&name=Working on Micropub
&category=indieweb

Response: 

HTTP/1.1 201 Created
Location: http://example.com/entry/1001
  • 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)
  • 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 in 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.

For example, creating a new "weight" measurement post as an h-entry with h-measure objects: 

h=entry
&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]=%

If you think you have found a case that requires a nested object, please document it on Micropub-brainstorming and feel free to drop in the IRC channel to discuss it.

Serveurs

Article principal : Micropub/Servers

Examples of Micropub endpoints are listed at Micropub/Servers.

Clients

Article principal : Micropub/Clients

Click through to the main article for a list of sites and client applications that publish via Micropub as well as a table indicating implementation statuses.

Bibliothèques

Open source libraries & implementations used to support micropub on the client app side and on the API endpoint side on the server:

Problèmes

Please use the Github repo for issues and discussion related to the spec.

For issues that have been discussed and are ready to consider for inclusion in the spec, use the Micropub-brainstorming page to collect examples and iterate on the ideas.

Voir aussi

Récupérée de « https://ducamp.me/index.php?title=Micropub&oldid=9005 »