piwi/mde-service

此包已被废弃，不再维护。作者建议使用 markdown-extended/mde-service 包。

在线解析 Markdown-Extended 内容的 webservice 工具

维护者

详细信息

github.com/piwi/mde-service

主页

源代码

安装: 33

依赖: 0

建议者: 0

安全: 0

星标: 0

关注者: 1

分支: 1

v0.1.1 2014-12-31 18:05 UTC

Requires

Apache-2.0 2153336d6469893c3c4a65ec1b75f2aeada91a66

markdownwebservicemarkdown-extended

This package is not auto-updated.

Last update: 2022-02-01 12:43:15 UTC

README

在线解析 Markdown-Extended 内容的 webservice 工具。

MDE-Service webservice 处理原始或 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":[]
}

此 webservice 在线可用，地址为 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 如果请求似乎格式不正确
  • 如果请求动词不被允许（除了 GET、POST 或 HEAD），将返回 405 方法不允许。
  • 如果在处理过程中发生错误，将返回 500 内部服务器错误。

解析内容的默认渲染是其元素的全聚合。

$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" ...

如果发生 MDE 解析，API 每个响应中嵌入的 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);