| 中国哲学书电子化计划 | |
| 简体字版 |
CTP API
中国哲学书电子化计划应用程式介面（CTP API）提供方法把CTP的内容和功能引入到其它线上工具和应用程序。本API由两个主要部分构成：首先插件API把外部的功能引入到CTP介面内，其次JSON API使得外部网站能够使用到 CTP的功能。
本页为有兴趣创造新插件的技术人员提供技术性说明。若您想要了解如何从使用者的角度使用已经存在的插件，您可以先参考插件使用说明页面。
插件API
插件API定义CTP站内的特殊功能连结出发点，使得这些出发点可连结到外部网站和用户自定工具。插件建设好了之后，其它使用者可选择把插件安装到自己的CTP帐户，安装方法不需要依靠技术性的知识。以下是已有插件的具体例子，供参考。
| 插件名称 | 插件说明 | 插件类型 | 应用例子 | 安装插件 |
|---|---|---|---|---|
| Text tools | Tools for textual analysis. | chapter（篇章）, book（书籍） | [Text tools] | [安装] |
| Annotate | Tools for textual annotation. | chapter（篇章） | [Annotate] | [安装] |
| Text tools (beta version) | Tools for textual analysis (beta version). | chapter（篇章）, book（书籍） | [Text tools (beta version)] | [安装] |
| 全文输出 | 输出原典全文。 | book（书籍）, chapter（篇章） | [全文输出] | [安装] |
| TextRef | List editions of a title on TextRef.org. | book（书籍） | [TextRef] | [安装] |
| 英华字典 | 在《英华字典》中查询。 | character（汉字）, word（字词） | [英华字典] | [安装] |
[显示更多...]
从技术上来讲，一个插件是以XML表示的对外连结程序化规格。插件必须为有效XML，也需要符合CTPPlugin DTD。以下是插件XML档的具体例子：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE CTPPlugin PUBLIC "CTPPlugin" "http://ctext.org/plugins/ctpplugin.dtd">
<CTPPlugin xmlns="http://schema.ctext.org/Plugin">
<Plugin>
<ShortName xml:lang="en">Plain text</ShortName>
<ShortName xml:lang="zh">全文输出</ShortName>
<Description xml:lang="en">Export a chapter as plain text.</Description>
<Description xml:lang="zh">输出原典全文。</Description>
<Url template="https://ctext.org/plugins/textexport/#{textRef}" pluginType="chapter" fieldEncoding="utf8" method="get" />
<Update src="https://ctext.org/plugins/textexport/plugin.xml" />
</Plugin>
</CTPPlugin>
以上插件例子当前版本的原始码可通过其更新URL下载参考。
若想要建立新的插件，可借用上述例子并按照下述说明作出所需要的修改：
- ShortName - 该插件的简短称呼标题。最长可达到20个字母。
- Description - 描述该插件的主要用途。最长可达到250个字母。
- URL - 表示该插件的URL模型。当使用者执行该插件时，系统会发送GET或POST请求到这个URL。该元素的性质如下：
- template （必要） - URL模型。系统会按照下述说明把相关内容复制到模型内。
- plugintype （必要） - 以英文逗号分割的列单，表示该插件所能接受的数据内容。有效值：“character”、“word“、”string“、”chapter“。
- fieldencoding - 下述价值其中之一：
价值 说明 范例 utf8 (default) UTF-8编码 %E4%BB%81 gb GB18030编码 %C8%CA big5 Big5编码 %A4%AF big5.hex Big5编码，以小写十六进制表示* a4af big5.HEX Big5编码，以大写十六进制表示* A4AF codepoint.hex Unicode编码，以小写十六进制表示* 4ec1 codepoint.HEX Unicode编码，以大写十六进制表示* 4EC1 - method - 提交方法："get"（默认）或"post"。
- Update - 一个HTTP资料包括该插件的XML数据。如有，src性质必须为相关的URL。系统会定期读取该URL的内容，当内容改变（且为有效CTP插件）时，插件将会在开通自动更新用户的帐户中进行自动更新。
URL模型
插件的"template"元素必须包括"src"属性指定一个模式用以自动创立指向指定资料的相关连结。"src"属性的内容是一个URL模式，其中包括下述一个（或以上）的项目。
| 栏位 | 相关类型 | Contents | 范例 |
|---|---|---|---|
| searchTerms | character, word, string | 一个（或以上）统一码中的汉字。 | 仁 |
| character.hanyudazidian | character | 该字在《汉语大字典》中出现的页数。 | 107 |
| character.gsr | character | 该字在《Grammata Serica Recensa》中出现的页数。 | 388 |
| textRef | book, chapter | 代表该原典文献的CTP URN。 | ctp:analects/xue-er |
| title | book | 代表该原典文献的书名。 | 韩非子 |
插件安装
每个CTP帐户都有独立的插件XML档案，该档案的内容表示帐户已安装的CTP插件状态。使用者可以通过个人设定页面中的插件部分查看或修改个人的插件档案。插件的安装就是把插件的内容加入使用者的插件档内。
为了便利使用者，可以透过浏览器上打开连结发送请求，把存放于网路上的XML插件档安装到使用者的个人帐户里。为了要求使用者安装特定插件，请先确认该插件为有效XML、符合CTP格式并可透过http访问。此后，要让使用者在浏览器中打开连结如下：
https://ctext.org/account.pl?if=gb&installplugin=[Plugin URL]&remap=gb如果希望插件安装完毕之后让使用者回到外部网站，可以另外提供return参数，其内容为安装后所欲打开的URL。
如果使用者尚未安装该插件，系统会确认是否要安装。如果已经安装了并且有提供return URL，使用者的浏览器会直接重定向该URL。
请注意：如果提供return URL，该URL的域名必须与原域名相同。
JSON API
CTP API的首要任务是实现客户端上的JavaScript应用透过CORS和CTP插件系统实现新功能。请注意：API的所有使用受使用上限及其它的条件。
如果想要使用JSON API，请参考现行版本的使用说明。
CTP URNs
CTP URN所指的是代表文献或文献其中一部分的标识符。CTP API和用户端可以交换这些标识符以指向特定的文献。例如，文献插件把一个URN传送到外部网站或工具代表使用者想要操作的原典内容；此后该URN可提供给JSON API函数以读出原典全文和相关后设资料。API的用户端必须把CTP URN本身视为不透明的标识符而不要试图去剖析它的结构内容，因为将来还会再推出新的URN，而新的URN结构未必与目前的相同。
CTP URN例子：
如同上述例子，在使用getlink的API函数时若同时把“redirect”设定为“1”则可直接在连结之际把CTP URN转换为ctext.org上的连结。如果需要自动读出ctext.org连结，可以使用readlink的API函数。错误处理
当系统无法实行API请求时，系统会返回一个JSON的“error”对象，其内容包括错误编码和错误解释，而系统不返回其它内容。错误编码和解释如下：
| 栏位 | 内容 |
|---|---|
| code | 固定编码（请参考下属表格）表示错误类型。 |
| html | 人类可读的错误解释，以html表示（可包含相关连结等内容） |
应用程序应该根据“code”（错误编码）进行错误处理，而如果有需要建议把“description”（错误解释）显示给使用者参考。尤其ERR_REQUEST_LIMIT等错误可能会需要使用者自行操作才能解决，因此特别推荐显示系统的错误解释。
有效的错误编码如下：
| 错误码 | 错误内容示范 |
|---|---|
| ERR_NOT_SUPPORTED | 尚未支持。 |
| ERR_INVALID_URN | URN无效。 |
| ERR_UNDEFINED_URN | 资料不存在。 |
| ERR_MISSING_PARAM | ______：缺少必须的参数“______”。 |
| ERR_REQUEST_LIMIT | 达到请求限制。请登入以存取更多内容。 |
| ERR_INVALID_VALUE | “______”不是“______”参数的有效参数值。 |
| ERR_INVALID_PARAM | ______：未知参数“______”。 |
| ERR_INVALID_FUNCTION | 未知函数。 |
| ERR_INVALID_APIKEY | 请求包括apikey参数，但此apikey不正确或已失效。 |
| ERR_GENERIC | [其他类型的错误。] |
| ERR_REQUIRES_AUTHENTICATION | 此操作需要认证才能执行。请使用已注册的IP地址，或提供有效的apikey。 |
访问条件
CTP API的主要目标是给第三方开发者提供方法创作新的用户端应用以扩展CTP本身的功能，而不试图提供方法下载大量资料。因此，API请求（尤其是针对原典全文的请求）将会根据用户组受到限制：
- 未经授权的使用者 - 没有登入CTP帐户并且不从订阅机构访问的使用者可以读取少数资料。
- 登入CTP帐户的使用者 - 已登入CTP帐户的使用者可读取较多资料。
- 订阅机构的使用者 - 订阅机构的使用者从已注册的IP地址访问可根据机构协议的条款访问资料。
为了确认使用者的用户组，可使用getstatus函数。
客户端
- ctext - Python的CTP API客户端。