| 中國哲學書電子化計劃 |
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]如果希望插件安裝完畢之後讓使用者回到外部網站，可以另外提供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客戶端。