markdown-extended/mde-service

一个在线解析Markdown-Extended内容的Web服务工具

维护者

详细信息

github.com/markdown-extended/mde-service

主页

源代码

安装: 22

依赖项: 1

建议者: 0

安全: 0

星标: 0

关注者: 2

分支: 1

v0.2.2 2024-02-25 20:41 UTC

Requires

Requires (Dev)

Replaces

Apache-2.0 20c021c00af2071f3f8ef19117a7f73237d52ca9

markdownwebservicemarkdown-extended

This package is not auto-updated.

Last update: 2024-09-22 23:10:51 UTC

README

一个在线解析Markdown-Extended内容的Web服务工具。

MDE-Service Web服务处理原始或JSON请求，并发送包含重要头信息的JSON内容响应。

基本使用方案是

$ curl -i http://localhost/mde-service/www/mde-api.php?source=%2AMarkdown%2A-__extended__%20content

HTTP/1.1 200 OK
Last-Modified: Mon, 29 Dec 2014 21:11:01 GMT
Content-Type: application/json; charset=utf-8
API-Status: 200 OK
API-Version: 0.1
MDE-Version: 0.1-gamma4
ETag: 8a4d0bef2b45148a6c8df14158704f6c

{
    "source":"*Markdown*-__extended__ content",
    "content":"\n\n<p><em>Markdown<\/em>-<strong>extended<\/strong> content<\/p>\n\n\n",
    "errors":[]
}

此Web服务可在http://api.aboutmde.org/上在线使用。

构建请求

您可以使用动词GET、POST或HEAD发送HTTP请求。GET和POST请求将产生相同的结果，而HEAD请求仅获取响应头。

接受的数据包括

  • source：要解析的原始单个MDE内容
  • sources：要解析的原始MDE内容表
  • options：传递给MDE解析器的选项表
  • format：用于MDE解析的格式（默认为HTML）
  • extract：要提取并返回的特定\MarkdownExtended\Content内容部分；这可以是“full”（默认）、“metadata”、“body”或“notes”；参见下面的说明以了解更多关于内容渲染的信息
  • source_type：使用此选项定义要处理的数据类型；默认为空（表示“data_input”），您可以将其设置为“file”以处理任何附件文件
  • debug：一个布尔值，用于获取一些调试信息

如果您指定了source和sources数据，单个source将被添加到sources表的末尾。

您可以定义一些特殊的头信息

  • Accept: application/json以准备响应格式
  • Time-Zone: Europe/Paris以使用特定时区；时区名称必须遵循Olson数据库，默认为UTC。

使用source_type=file选项，您可以上传一个或多个文件，其内容将作为sources解析。

理解响应

响应是一个带有重要状态码头信息的JSON编码内容。

JSON内容构建如下

  • errors：错误字符串表
  • dump：序列化的接口对象（仅调试模式下有效）
  • source：如果它是单个的，则已解析的接收到的MDE源
  • content：如果它是单个的，则已解析的源
  • sources：如果它们是多个的，则接收到的MDE源索引表
  • contents：如果它们是多个的，则MDE源解析版本的索引表；索引与sources元素相同。

响应状态可以是

  • 200 OK如果没有发生错误
  • 304 Not Modified如果请求包含ETag或If-Modified-Since头信息，并且响应未修改
  • 400 Bad Request如果请求看起来不正确
  • 405 Method Not Allowed如果请求动词不被允许（不是GET、POST或HEAD）
  • 500 Internal Server Error如果在处理过程中发生错误。

已解析内容的默认渲染是其元素的完整聚合

$mde_content->getMetadataToString()
\n
$mde_content->getBody()
\n
$mde_content->getNotesToString()

使用extract参数，您可以选择要返回的单个元素。

当源来自一个或多个上传的文件时，文件名将以与结果 contents 数组相同的索引在 sources 数组中呈现。

版本信息

API的每个响应都将包含一个带有当前API版本号的API-Version头。您可以使用它来检查您是否仍在使用正确的版本。

如果发生内容解析，响应还将包含一个带有MarkdownExtended解析器版本号的MDE-Version头。此引用应该是http://github.com/piwi/markdown-extended软件包的一个版本。

缓存响应

API的响应不会被缓存（这没有意义）。但是，您可以在响应被修改时才请求更新信息。您可以通过重新使用之前响应中的ETag头并将其作为请求中的If-None-Match头的值来做到这一点。

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

如果API响应中发生MDE解析，则嵌入的ETag是使用原始源和它们的解析内容构建的。这样，如果您使用上述头，只有在您发送了相同的源且结果未更新时，您才会收到304 Not Modified状态响应。

实现示例

命令行使用

以下示例可以在命令行中使用curl运行。每个示例都会在终端中获取响应头和内容。要获取仅内容（在实际生活中），请删除-i选项。

options参数在每个请求中显示为空，但不是必需的。

基本POST请求的使用方法

$ curl -i \
    --request POST \
    --data-urlencode "source=My *test* MDE **content** ... azerty \`azerty()\` azerty <http://google.com/> azerty." \
    --data-urlencode "options={}" \
    http://api.aboutmde.org/mde-api.php ;

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Status: 200 OK
API-Version: 0.1
MDE-Version: 0.1-gamma4
Last-Modified: Wed, 31 Dec 2014 00:57:32 GMT
ETag: c6989875115e90dc377c460c4801734c

{
    "source":"My *test* MDE **content** ... azerty `azerty()` azerty <http:\/\/google.com\/> azerty.",
    "content":"\n\n<p>My <em>test<\/em> MDE <strong>content<\/strong> ... azerty <code>azerty()<\/code> azerty <a href=\"http:\/\/google.com\/\" title=\"See online http:\/\/google.com\/\">http:\/\/google.com\/<\/a> azerty.<\/p>\n\n\n",
    "errors":[]
}

基本GET请求的使用方法

$ curl -i \
    --get \
    --data-urlencode "source=My *test* MDE **content** ... azerty \`azerty()\` azerty <http://google.com/> azerty." \
    --data-urlencode "options={}" \
    http://api.aboutmde.org/mde-api.php ;
    
# same output ...

带有JSON编码参数的POST请求可以通过以下方式制作

$ echo "{ \
    \"source\":     \"My *test* MDE **content** ... azerty \`azerty()\` azerty <http://google.com/> azerty.\", \
    \"options\":    \"{}\" \
    }" | curl -i \
        --request POST \
        --header "Content-Type: application/json" \
        --data @- \
        http://api.aboutmde.org/mde-api.php ;

# same output ...

您可以在请求中定义个人头信息

$ curl -i \
    --header "Time-Zone: Europe/Paris" \
    --request POST \
    --data-urlencode "source=My *test* MDE **content** ... azerty \`azerty()\` azerty <http://google.com/> azerty." \
    --data-urlencode "options={}" \
    http://api.aboutmde.org/mde-api.php ;

# same output ...

要上传文件，请使用

$ curl -i \
    --form "source=@my-file.md" \
    --form "source_type=file" \
    http://api.aboutmde.org/mde-api.php ;
    
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
API-Status: 200 OK
API-Version: 0.1
MDE-Version: 0.1-gamma4
Last-Modified: Wed, 31 Dec 2014 00:57:32 GMT
ETag: c6989875115e90dc377c460c4801734c

{
    "source":["my-file.md"],
    "content":"\n\n<p>My <em>test<\/em> MDE <strong>content<\/strong> ... azerty <code>azerty()<\/code> azerty <a href=\"http:\/\/google.com\/\" title=\"See online http:\/\/google.com\/\">http:\/\/google.com\/<\/a> azerty.<\/p>\n\n\n",
    "errors":[]
}

在出现错误的情况下，您将获得

$ curl -i \
    --request INPUT \
    --data-urlencode "source=My *test* MDE **content** ... azerty \`azerty()\` azerty <http://google.com/> azerty." \
    --data-urlencode "options={}" \
    http://api.aboutmde.org/mde-api.php ;

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json; charset=utf-8
API-Status: 405 Method Not Allowed
API-Version: 0.1

{
    "sources":[],
    "contents":[],
    "errors":["Request method \"INPUT\" is not allowed!"]
}

JavaScript实现

以下是通过XMLHttpRequest对象使用该接口的JavaScript使用示例。

// open a new XHR request handler
var xhr = new XMLHttpRequest();

// define a response callback
xhr.onreadystatechange  = function() {
    if (xhr.readyState  == 4) {

        // the response is always a JSON content
        var response = JSON.parse(xhr.response);

        // the response can have multiple "status" header:
        // 200 : no error
        if (xhr.status  == 200) {

            // if response.content is not empty
            if (response.content.length > 0) {
                var ajax_response = response.content;

            // else an error occurred
            } else {
                console.error("Error on XHR response:\n" + response.errors.join('\n'));

            }

        // 400 : bad request
        } else if (xhr.status  == 400) {
            console.error('Bad request!' + response.errors.join('\n'));

        // 405 : bad method (this one should never happen here)
        } else if (xhr.status  == 405) {
            console.error('Bad request method!' + response.errors.join('\n'));

        // 500 : any other error
        } else if (xhr.status  == 500) {
            console.error('Internal server error!' + response.errors.join('\n'));

        }
    }
};

// these are just for the example
var opts = {
    source:     'My *test* MDE **content** ... azerty `azerty()` azerty <http://google.com/> azerty.',
    options:    {}
};

// build the request data
var raw_data = "options=" + encodeURIComponent(JSON.stringify(opts.options)) + "&"
    + "source=" + encodeURIComponent(opts.source);

// make the POST request
xhr.open("POST", "mde_editor_interface.php", true);
xhr.setRequestHeader("Content-Type", "application/x-www-form-urlencoded");
xhr.send(raw_data);

// you can also make a simple GET request with the same data
xhr.open("GET", "mde_editor_interface.php?" + raw_data, true);
xhr.send();

// you can also post a JSON table
xhr.open("POST", "mde_editor_interface.php", true);
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(JSON.stringify(opts));

PHP实现

以下是通过cURL请求使用该接口的PHP使用示例。

// these are just for the example
$mde_options    = array();
$mde_source     = 'My *test* MDE **content** ... azerty `azerty()` azerty <http://google.com/> azerty.';

// send a post request
$curl_handler = curl_init();
curl_setopt($curl_handler, CURLOPT_URL, '.../www/mde-api.php');
curl_setopt($curl_handler, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl_handler, CURLOPT_POST, true);
curl_setopt($curl_handler, CURLOPT_POSTFIELDS, array(
                                                   'options'   => json_encode($mde_options),
                                                   'source'    => $mde_source,
                                               ));

$curl_response = curl_exec($curl_handler);

// print the 'content' result if no error
if (!curl_errno($curl_handler)) {
    $curl_response = json_decode($curl_response, true);
    $curl_info = curl_getinfo($curl_handler);
    echo $curl_info['content'];
} else {
    echo 'ERROR : ' . curl_error($curl_handler);
}
curl_close($curl_handler);