はじめに

本説明書では、星空文庫の作品及び作者情報を取得するためのAPIについて、その利用方法を説明します。

API一覧

API利用の流れ

最初に/api/summaryを呼び出し、作品リスト及び作者リストのページ数、および最終更新時刻を得ます。

次に、/api/summaryより得た情報を元に、/api/work-list及び/api/author-listを呼び出し、アプリケーション側に最新の作品リスト及び作者リストを構築します。

最後に、アプリケーションユーザーの操作に応じて、必要となった個別作品の詳細情報あるいは個別作者の作品リストを、/api/workあるいは/api/authorを用いて取得します。
各々のAPIについて、詳しくは別章をご参照下さい。

HTTPリクエスト

API呼び出し時の引数は、HTTPリクエストのクエリ文字列として指定します。
たとえば、https://slib.net/api/work-list?page=2としたり、あるいはhttps://slib.net/api/work?id=100として指定します。

結果データの情報制限

API呼び出し時の引数にresponse引数を付けることで、結果データの一部を省略することが可能になります。

以下の様に指定します。

https://slib.net/api/work?id=100&response=nochapter

各引数によって制限される項目は、各拡張型及び各API引数のresponse列を参照してください。記されている省略表記のresponse引数で呼び出された時、その項目は省略されずに結果データに含まれます。
表にresponse列が存在しない場合、response引数に関係なく、全ての情報が結果データに含まれます。

構成

本章では、API利用に関する全体の流れと、大きな章を設けなくとも説明が可能な項目について説明を行いました。
後に続く2章では結果XML の書式について、3章ではやり取りされるデータ型について、4章では各APIについて、それぞれ説明します。

書式

結果はXMLとして返されます。
必ず以下の様な形式を取ります。

<?xml version="1.3" encoding="UTF-8"?>
<result xmlns="urn:slib:net:api:******">
<version>1.3</version>
:
:
:
</result>

最初にxmlの定義（及び文字コード指定）があり、その後にresult要素が1つだけ現れます。このresult要素の中に、全ての結果情報が含まれます。resultの属性であるxmlnsは必ず「urn:slib:net:api:******」の形式になっており、「******」の部分はAPIごとに固定です。
なお、結果XMLを構成する各要素は、スカラ値／配列／連想配列の3種類のデータ表現から構成されます。そしてそれらは、一定ルールに基づくことで、パースすることが可能です。一番外側のresult要素は、必ず、連想配列データの扱いとなります。result要素は必ずversionという子要素を持っています。

versionはスカラ値データであり、その値は現時点では常に1.3となります。ここに1.3以外の値が来た場合、本説明書に記されていない未知の規則が適用されている可能性があります。
なお、各APIの説明の項において、versionについて省略しておりますが、実際に得られるデータ中にはversion子要素が存在することに注意して下さい。

スカラ値

スカラ値は、文字列や数値といった単体で存在するデータです。
XML内では、以下の様な形式で表されます。

<scala>hoge</scala>

※scalaの部分は例であり、ここにはデータ名が来ます。
hogeの部分が、スカラ値データにあたります。
なお、XML内においてスカラ値データは、特殊文字が以下の様にエンコードされています。

配列

配列は、データの羅列からなるデータです。
XML内では、以下の様な形式で表されるデータです。

<data-list type=”array”>
<data> ... </data>
<data> ... </data>
:
:
<data> ... </data>
</data-list>

※dataの部分は例であり、ここにはデータ名が来ます。
各「...」の部分には、配列要素のデータが来ます。
外側の開始タグにはtype="array"が付き、要素名はデータ名に「-list」の接尾辞が付いたものとなります。

並べられたデータには順序がありますが、名前はついておりません。内側の要素名は全てデータ名と一致します。

配列内の要素のデータ型は、スカラ値または連想配列となります。また、同一配列内の各要素のデータ型は必ず一致します。

連想配列

連想配列は、名前のついたデータの羅列からなるデータです。
XML内では、以下の様な形式で表されるデータです。

<obj>
<hoge> ... </hoge>
<fuga> ... </fuga>
<foo> ... </foo>
<bar> ... </bar>
</obj>

※objの部分は例であり、ここには連想配列データのデータ名が来ます。
また、hoge, fuga, foo, barの部分も例であり、各々の子要素のデータ名が来ます。

連想配列内の各要素のデータ型には、制限がありません。
また、各要素ごとのデータ型は個別に定まり、同一とは限りません。
詳細については、拡張データ型の定義に従って下さい。

基本データ型

基本的なデータ型については、以下の様に定めます。

拡張データ型

連想配列であるobjectは、状況に合わせ様々な子要素を持ちます。
以下に、各拡張データ型について定義します。
ただし、同じ拡張データ型であっても、呼び出すAPIによっては、子要素の一部が存在しない場合があります。

列挙型

enum-uint型データの各整数値が示す値の意味を、以下に示します。

/api/summary

/api/work-list

/api/work

/api/author-list

/api/author

星空文庫APIは、利用規約に同意の上、ガイドラインに従ってご利用ください

• 星空文庫APIガイドライン