Build the request

You can send HTTP requests using verbs GET, POST or HEAD. The GET and POST
requests will have the same results while the HEAD one will only fetch response headers.

Accepted data are:

source : the original single MDE content to parse

sources : a table of original MDE contents to parse

options : a table of options to pass to the MDE parser

format : the format to use for the MDE parsing (default is HTML)

extract : a specific \MarkdownExtended\Content
content part to extract and return ; this can be "full" (default), "metadata", "body" or "notes" ;
see the note below to learn more about the rendering of a content

source_type : use this to define the type of sources to treat ; default is empty (which means
"data_input") and you can set it to "file" to treat any attached file

debug : a boolean value to get some debugging information

If you specify both source and sources data, the single source will be added
at the end of the sources table.

You can optionally define some special headers:

Accept: application/json to prepare the response format

Time-Zone: Europe/Paris to use a specific timezone ; the time-zone name must follow the
the Olson database and
defaults to UTC.

Using the source_type=file option, you can upload one or more files and
their contents will be parsed as the sources.

Understand the response

The response is a JSON encoded content with a significant status code header.

The JSON content is built like:

errors : a table of error strings

dump : the serialized interface object (in debug mode only)

source : the received MDE source that has been parsed if it was single

content : the parsed version of the source if it was single

sources : an indexed table of received MDE sources if they were multiple

contents : an indexed table of the parsed versions of the MDE sources if they were multiple ;
indexes are the same as for the sources elements.

The response status can be:

200 OK if nothing went wrong

304 Not Modified if the request contains an ETag or a If-Modified-Since header and the response is not modified

400 Bad Request if the request seems malformed

405 Method Not Allowed if the request verb was not allowed (anything else than GET, POST or HEAD)

500 Internal Server Error if an error occurred during the process.

The default rendering of a parsed content is a full aggregation of its elements:

Using the extract argument, you can choose a single element to return.

When the sources came from one or more uploaded files, the filenames are rendered in the sources array
with the same index as in the resulting contents array.

Versions information

Each response of the API will have a API-Version header with the current API version number. You
can use it to check that you are still working with the right version.

If a content parsing happens, the response will also have a MDE-Version header with the version
number of the MarkdownExtended parser used. This reference should be a release of the package
http://github.com/piwi/markdown-extended.

Caching responses

The responses of the API are not cached (this would have no sense). But you can make a request with
information to update your content only if the response is modified. You can do so by re-using the
ETag header of a previous response you had and send it as a value of a If-None-Match header in
your request:

$ curl --header "If-None-Match: YOUR_PREVIOUS_RESPONSE_ETAG" ...

The ETag embedded in each response of the API if an MDE parsing happens is built with the original
sources AND their parsed contents. This way, if you use the header above you will have the 304 Not Modified
status response only if you sent the same source AND if the result is not updated.

Implementation examples

Command line usage

The examples below can be run in command line using curl.
Each of them will fetch the response headers and its content on the terminal. To get only
the content ("in-real-life"), delete the -i option.

The options argument is shown empty in each request but is not required.