Voir la source de Micropub

'''<dfn>Micropub</dfn>''' 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 [[article]]s, des [[note]]s courtes, des [[reply|commentaires]], des [[like]]s, des [[photo]]s, des [[event|événements]]s, ou d'autres types de [[posts]] sur votre propre site.

{{new}} '''Submit an implementation report for Micropub to help the specification advance at W3C!'''
* Start here: https://micropub.rocks/

[[File:w3c-spec-REC.svg]]

__TOC__


== 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[http://www.w3.org/TR/html5/forms.html#url-encoded-form-data], multipart formulaire-data [http://www.w3.org/TR/html5/forms.html#multipart-form-data], 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 [https://tools.ietf.org/html/rfc7159], en fonction de HTTP Accept [http://tools.ietf.org/html /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 &lt;link&gt; tag in the HTML head of your home page, or send an HTTP Link header.

==== HTTP Header ====
<pre>Link: &lt;https://example.com/micropub&gt;; rel="micropub"</pre>

==== HTML Head ====
<pre>&lt;link rel="micropub" href="https://example.com/micropub"&gt;</pre>

=== Authentification ===
Micropub requests are authenticated by including a Bearer Token in either the HTTP header or a form-encoded body parameter as described in the [http://tools.ietf.org/html/rfc6750#section-2 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.

==== En-tête HTTP ====
<pre>
Authorization: Bearer XXXXXXXX
</pre>

==== Form-Encoded Body Parameter ====
<pre>
access_token=XXXXXXXXX
</pre>

=== 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.

=== Vérification ===
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.


=== Exemples de Création d'Objets ===
Comment créer quelques uns des [[:Category:PostType|types de post]] communs

==== Indiquer l'objet étant créé ====

Pour indiquer l'objet étant créé utilisez une propriété appelée "h", (qui ne serait jamais le nom d'une propriété ou d'un objet microformats), suivie du nom de l'objet microfomats. Examples :

* h=entry
* h=card
* h=event
* h=cite

==== h-entry ====

Les propriétés suivantes peuvent être incluses dans une requête pour créer un nouvel [[h-entry]] :

* name
* summary
* content
* published
* updated
* category = tag1, tag2, tag3 (sent as array syntax: <code>&category[]=tag1&category[]=tag2</code>)
* location
** as a [http://tools.ietf.org/html/rfc5870 Geo URI], for example <code>geo:45.51533714,-122.646538633</code>
*** GeoURIs allow [https://tools.ietf.org/html/rfc5870#section-6.4 additional parameters] that may be used to include the title of a location: <code>geo:1,2;name=Somewhere</code>
** as a URL that contains an [[h-card]]
** My micropub client currently has a map to mark the specific location in LatLng values, and a text input for an actual place name. So my client is sending a request of the form "&location=1.23,%40-4.56:An%40Address" [[User:Jonnybarnes.net|Jonnybarnes.net]] 07:57, 10 June 2014 (PDT)
* 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]] = <nowiki>https://myfavoritesocialnetwork.example/aaronpk, https://archive.org/</nowiki>, 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 =====

Poster une nouvelle [[note]] avec des tags, syndicant vers monréseausocialfavori : 

* content
* category
* mp-syndicate-to
* published (optional, defaults to "now" if not present. Useful for writing offline and syncing later)

<pre>
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
</pre>

====== Exemple minimal ======
<pre>
POST /micropub HTTP/1.1
Host: example.com
Content-type: application/x-www-form-urlencoded
Authorization: Bearer XXXXXXX

h=entry
&content=Hello+World
</pre>

<pre>
curl https://example.com/micropub -d h=entry -d "content=Hello World" -H "Authorization: Bearer XXXXXXX"
</pre>

===== Nouvelle Réponse =====

Posting a new [[reply]], syndicating to myfavoritesocialnetwork

* content
* in-reply-to
* mp-syndicate-to
* published

<pre>
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
</pre>

===== Nouveau Repost =====

Posting a new [[repost]], and adding additional tags.

* repost-of
* category

<pre>
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
</pre>

===== Nouvel Article =====

Poster un nouvel [[article]]

* content
* name
* category
* published

<pre>
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
</pre>

===== Nouveau Signet =====

Poster un nouveau [[bookmark]] avec nom, citation et tags.

* bookmark-of
* name
* content
* category

<pre>
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
</pre>


===== Ajouter des Fichiers =====

When a Micropub request includes a file, the entire request is sent in the <code>multipart/form-data</code> 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 <code>$_FILES</code> 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|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

<pre>
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/
</pre>


==== h-cite ====

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

(The following list is from [http://microformats.org/wiki/h-cite#Properties 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 [http://en.wikipedia.org/wiki/Geo_URI Geo URI] such as <code>geo:37.786971,-122.399677</code>

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:

<pre>
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
</pre>

Response:

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

Then create the checkin post:

<pre>
POST /micropub

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

Response:

<pre>
HTTP/1.1 201 Created
Location: http://example.com/entry/1001
</pre>

* 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:

<pre>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]=%</pre>

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 ==
{{main|Micropub/Servers}}

Examples of Micropub endpoints are listed at [[Micropub/Servers]].

== Clients ==

{{main|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 ==
<span id="Open Source"></span>
Open source libraries & <span id="Implementations">implementations</span> used to support micropub on the client app side and on the API endpoint side on the server:
* [https://github.com/aaronpk/p3k-micropub p3k-micropub] '''PHP''' library used in [[p3k]]
* [https://github.com/taproot/authentication taproot/authentication] '''PHP''' library used in [[Taproot]], implements both client app and resource provider authentication
* [https://github.com/snarfed/wordpress-micropub wordpress-micropub]: [[WordPress]] plugin for server endpoint
* [https://github.com/kylewm/flask-micropub flask-micropub]: [[Flask]] ([[Python]]) plugin that makes it easy to add IndieAuth authentication and Micropub authorization to a client application.
* [https://github.com/voxpelli/node-micropub-express micropub-express] '''Node.js''' server library created and used by {{voxpelli}} for voxpelli.com's micropub endpoint
* [https://www.npmjs.com/package/micropub-helper micropub-helper] '''Node.js''' client library created and used by [[grant.codes]]

== Problèmes ==
Please use the [https://github.com/w3c/Micropub/issues 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 ==
* [http://micropub.net/draft/ Latest Editor's Draft]
* <span id="Brainstorming">[[Micropub-brainstorming]]</span>
* [[Micropub-extensions]]
* [[post]] - [[h-entry]]
* [[event]] - [[h-event]]
* [[obtaining-an-access-token]]
* [[token-endpoint]]
* [[micropub-endpoint]]
* [[access_token]]
* [[incremental authorization]]
* [[micropub media endpoint]]

[[Category:IndieAuth]]
[[Category:building-blocks]]
[[Category:Micropub]]