Micropub Request function

[EdwardHinkle]

There should be a function (maybe class?) that receives a Micropub Post struct and uses that to send the post either formencoded or JSON based on the lowest required format. It should also handle knowing if there is a Media Endpoint, and if so, uploading the files there instead of via multipart.

Media Endpoint uploads should have a function that can be triggered while using the posting UI, but it should also be supported that if you call the Micropub create or update function while media endpoint uploads are still running, the framework should see that and set the ACTUAL request to start once the uploads are finished.

There should also be a property that allows a view to know the status ("Uploading", "Sending", etc).

3.1
All Micropub requests to create posts are sent as UTF-8 x-www-form-urlencoded, multipart/form-data [HTML5], or [JSON]-encoded HTTP requests. Responses typically do not include a response body, indicating the needed information (such as the URL of the created post) in HTTP headers. When a response body is necessary, it should be returned as a [JSON] encoded object.

3.1.1 Form-Encoded and Multipart Requests

For x-www-form-urlencoded and multipart/form-data requests, Micropub supports an extension of the standard URL encoding that includes explicit indicators of multi-valued properties. Specifically, this means in order to send multiple values for a given property, you must append square brackets [] to the property name.

For example, to specify multiple values for the property "category", the request would include category[]=foo&category[]=bar.

This works equally well in multipart requests, where each value is given in a separate "part" of the request, and the name is given in a line such as Content-Disposition: form-data; name="category[]".

Note that the extent of the extensions to the x-www-form-urlencoded syntax is the addition of the square brackets to indicate an array. Syntax such as foo[0] and foo[bar] is not supported, and so clients are expected to use the JSON syntax when posting more complex objects.

3.2 Reserved Properties

A few POST body property names are reserved when requests are sent as x-www-form-urlencoded or multipart/form-data.

access_token - the OAuth Bearer token authenticating the request (the access token may be sent in an HTTP Authorization header or this form parameter)
h - used to specify the object type being created
action - indicates whether this is an delete, or undelete (updates are not supported in the form-encoded syntax)
url - indicates the URL of the object being acted on
mp-* - reserved for future use
When creating posts using x-www-form-urlencoded or multipart/form-data requests, all other properties in the request are considered properties of the object being created.

3.3 Create

To create a post, send an HTTP POST request to the Micropub endpoint indicating the type of post you are creating, as well as specifying the properties of the post. If no type is specified, the default type [h-entry] should be used. Clients and servers must support creating posts using the x-www-form-urlencoded syntax, and may also support creating posts using the JSON syntax.

h={Microformats object type}
e.g., h=entry

All parameters not beginning with "mp-" are properties of the object being created.

e.g., content=hello+world

To specify multiple values for a property, such as multiple categories of an h-entry, append square brackets to the property name, indicating it is an array.

e.g., category[]=foo&category[]=bar

Properties that accept multiple values must also accept a single value, with or without the square brackets.

3.3.1 Uploading Files

To upload files, the client must check for the presence of a Media Endpoint. If there is no Media Endpoint, the client can assume that the Micropub endpoint accepts files directly, and can send the request to it directly. To upload a file to the Micropub endpoint, format the whole request as multipart/form-data and send the file(s) as a standard property.

For example, to upload a photo with a caption, send a request that contains three parts, named h, content and photo.

For properties that can accept a file upload (such as photo or video), the Micropub endpoint must also accept a URL value, treating that the same as if the file had been uploaded directly. The endpoint may download [Fetch] a copy of the file at the URL and store it the same way it would store the file if it had been uploaded directly.

3.3.2 JSON Syntax

In order to support more complex values of properties, you can create a post with JSON syntax by sending the entry in the parsed Microformats 2 JSON format.

Note that in this case, you cannot also upload a file, you can only reference files by URL as described above.

When creating posts in JSON format, all values must be specified as arrays, even if there is only one value, identical to the Microformats 2 JSON format. This request is sent with a content type of application/json.

3.3.6 Response

When the post is created, the Micropub endpoint must return either an HTTP 201 Created status code or HTTP 202 Accepted code, and must return a Location header indicating the URL of the created post. [RFC2616]

If the endpoint chooses to process the request asynchronously rather than creating and storing the post immediately, it must return an HTTP 202 Accepted status code, and must also return the Location header. The server must do any error checking and validation of the request synchronously in order to ensure the object will be created successfully, prior to returning HTTP 202. Clients will expect the object at the indicated URL to exist at some point in the (near) future if they receive an HTTP 202 response.

If the target also provides a shortlink, or if it syndicated the post to another location, the Micropub endpoint may return additional URLs using the HTTP Link header, along with an appropriate "rel" value. For example, it can return the short URL of a post by responding with:

Link: http://aaron.pk/xxxxx; rel="shortlink"
or can include the location of the syndicated post with:
Link: https://myfavoritesocialnetwork.example/aaronpk/xxxxxx; rel="syndication"
Error Response

See the "Error Response" section below for details on how to indicate an error occurred.

3.6 Media Endpoint
In order to provide a better user experience for Micropub applications, as well as to overcome the limitation of being unable to upload a file with the JSON syntax, a Micropub server may support a "Media Endpoint". The role of the Media Endpoint is exclusively to handle file uploads and return a URL that can be used in a subsequent Micropub request.

When a Micropub server supports a Media Endpoint, clients can start uploading a photo or other media right away while the user is still creating other parts of the post. The diagram below illustrates a user interface that demonstrates creating a photo post while the photo is uploading asynchronously.

The above user flow applies just as well to mobile apps as it does to desktop apps. In general, the user experience of an application can be improved by having more of the work done asynchronously, giving the user a chance to continue working instead of waiting for the system to finish.