ハッカソン#20150504

h1. インタフェース仕様

----

{{>toc}}

h2. Questionクラス

一つ一つの "問題" に相当するクラス。問題データの入れ物。
アプリケーションによる問題取得の際に、QuestionDBクラスによって生成される。
アプリケーションによる新規問題作成の際は、別クラスにより生成する予定。（T.B.D.）

h3. プロパティ

| 名前 | 型 | 説明 |
| id | int | 問題の識別子 |
| question | stirng | 問題文 |
| correctAnswers | array<string> | 正解となる選択肢群。配列形式。 |
| incorrectAnswers | array<string> | 不正解となる選択肢群。配列形式。 |

h3. メソッド

| 名前 | 応答値 | 引数 | 説明 |
| get*** | 各プロパティ | なし | 各プロパティのアクセサ（getter）。***はプロパティ名を表す。 |
| set*** | なし | 各プロパティ | 各プロパティのアクセサ（setter）。***はプロパティ名を表す。 |
| isCorrect | bool | string | 指定した文字列が正解群（correctAnswers）に含まれるか否かの真偽値を応答する。 |
| getCorrectAnswersInJSON | string | なし | 正解群をJSON配列形式で応答する。ex) ["answer1", "answer2", "answer3"] |
| getIncorrectAnswersInJSON | string | なし | 不正解群をJSON配列形式で応答する。ex) ["answer1", "answer2", "answer3"] |

----

h2. QuestionDBクラス

アプリケーションがデータベースにアクセスする際に使用するアクセサクラス。

h3. メソッド

| 関数名 | 応答値 | 引数 | 説明 |
| getNumberOfQuestions | int 総問題数 | なし | 現在の総問題数を応答する。 |
| getQuestion | Question | なし | 問題を1つランダムに取り出し、応答する。 |
| getQuestionById | Question | int 問題の識別子 | 指定した識別子の問題を取り出し、応答する。 |
| getQuestions | array<Question> | int 問題数 | 指定した個数の問題をランダムに取り出し、配列形式で応答する。（※1参照） |
| setQuestion | int 登録/更新時の問題の識別子(=id) | Question 問題 | 指定した問題を登録する。（※2参照） |

※1.
　問題は重複しないものとする。
　ただし、引数に指定された問題数が総問題数を上回る場合は問題の重複を許し、指定数分の問題を応答する。
※2.
　idが既存の場合は、当該idの問題に対して問題文/正解群/不正解群を上書きし、当該idを応答する。
　idが既存でない場合は、当該idを無視して新規登録を行ない、新規登録時のidを応答する。

----

h2. Questionerクラス

クライアントアプリケーションからのリクエストに対応するレスポンスを行なうクラス。

h3. 外部I/F（HTTPリクエスト）

クライアント側とサーバ側との間で、下記の属性群のやりとりを行なう。
なお、HTTPのメソッドは GET / POST のどちらかを利用するものとし、どちらを利用するかはサーバ側のソースコード上で簡単に切り替えられるものとする。

| 属性名 | 属性値 | 説明 |
| request | QuestionDBクラスのメソッド名 | リクエストの要旨を指定する。 |
| arguments | 引数群 | 属性requestで指定するメソッドの引数を、JSON配列形式で指定する。 |

h3. request毎の入出力形式

| request名 | 引数の形式 | 引数の例 | 応答の形式 | 応答の例 |
| getNumberOfQuestions | なし | なし | {"getNumberOfQuestions" : "総問題数"} | {"getNumberOfQuestions" : "124"} |
| getQuestion | なし | なし | {"getQuestion" : 問題} | {"getQuestion" : ["7", "これは質問文です（ID=7）", ["正答1"], ["誤答1", "誤答2", "誤答3"]]} |
| getQuestionById | ["問題の識別子"] | ["5"] | {"getQuestionById" : 問題} | {"getQuestionById" : ["5", "これは質問文です（ID=5）", ["正答1"], ["誤答1", "誤答2", "誤答3"]]} |
| getQuestions | ["問題数"] | ["2"] | {"getQuestions" : 問題群} | {"getQuestions" : [["8", "これは質問文です（ID=8）", ["正答1"], ["誤答1", "誤答2", "誤答3"]], ["5", "これは質問文です（ID=5）", ["正答1"], ["誤答1", "誤答2", "誤答3"]]]} |
| setQuestion | [問題] | [["", "ここは質問文です", ["正答1"], ["誤答1", "誤答2", "誤答3"]]] | なし | なし |

h3. 使用例

以下のようにHTTPリクエスト（例はGETメソッド）を送信する。これは、ランダムに3問を出力するリクエストに相当する。
（※アンパサンド「&」の直前にエスケープ「\」を挿入している点に注意されたい。）

<pre>
$ curl -g 'http://www.fukurous.org/path/to/Questioner.php?request=getQuestions\&arguments=["3"]'
</pre>

すると、リクエストに対応して、以下のレスポンスが得られる。（整形は説明都合であり、実際のレスポンスでは整形不要。）

<pre>
{
"getQuestions" :
[
["4", "これは質問文です（ID=4）", ["正答1", "正答2"], ["誤答1", "誤答2", "誤答3"]],
["3", "これは質問文です（ID=3）", ["正答1"], ["誤答1", "誤答2", "誤答3", "誤答4", "誤答5"]],
["7", "これは質問文です（ID=7）", ["正答1"], ["誤答1", "誤答2", "誤答3"]]
]
}
</pre>

次のリクエストは、問題を新規登録（＝ID指定なしで登録）するリクエストに相当する。

<pre>
$ curl -g 'http://www.fukurous.org/path/to/Questioner.php?request=setQuestion\&arguments=[["", &#39;http://www.fukurous.org/path/to/Questioner.php?request=setQuestion&amp;arguments=[[&quot;&quot;, "ここは質問文です", ["正答1"], ["誤答1", "誤答2", "誤答3"]]]'
</pre>

上述の通り、リクエスト "setQuestion" は特にレスポンスを必要としない。