基本の作成、読み取り、更新、削除の各操作は、共通の REST API 規則に従って提供されます。エレメント・タイプの最上位 URL は、そのタイプの項目のコレクションを表します。そのタイプのすべてのエレメントのリストを JSON オブジェクトの配列としてレンダリングするには、HTTP メソッド GET を適切な HTTP ヘッダー、または json 照会パラメーターと共に使用します。新規エレメントを作成するには、適切なタイプの最上位 URL に HTTP メソッド POST を使用し、要求の本体でエレメントの JSON データを提供します。応答本体には、サーバー生成の id プロパティーを含め、新規エレメントのフル JSON 表記を含めます。また、JSON オブジェクトの配列を提供して、単一要求で複数のエレメントを作成することもできます。この場合、応答本体には、要求に指定されたのと同じ順序で新規エレメントの JSON 配列が含まれます。同様に、エレメントの JSON 配列と共に HTTP PUT メソッドを使用することにより、複数のエレメントのデータを更新することができます。フル JSON エレメントを含むか、エレメントの UUID のみを含む JSON 配列と共に HTTP DELETE メソッドを使用することにより、複数のエレメントを削除することができます。
単一の既存エレメントに対して操作を実行するには、そのエレメントの UUID を、そのタイプの最上位 URL に付加します。例えば、提供されているサンプル・リリースの JSON データにアクセスするには、URL http://base_url/releases/00000000-0000-0000-0000-000000000036/ と共に HTTP メソッド GET を使用します。エレメントのデータを更新するには、HTTP PUT メソッドを使用し、更新された JSON オブジェクトを要求本体に提供します。(この場合、要求 URL 内の UUID は、要求本体内の id プロパティーに優先します。) エレメントを削除するには、HTTP DELETE メソッドを使用します。その場合、要求本体は必要ありません。
作成、読み取り、および更新の各操作 (POST、GET、および PUT) を使用する場合、オプションの format 照会パラメーターを含めて、特定のユース・ケース用に JSON 出力を調整することができます。このパラメーターを提供しない場合、またはパラメーターの値が認識されない場合は、デフォルトのフォーマットが使用されます。各エレメント・タイプは、異なるフォーマット・セットをサポートしています。これらのフォーマットは、エレメント・タイプの参照情報と共にリストされています。フォーマットの中には大量の詳細を表示するものもあれば、少量の詳細を表示するものもありますが、その違いは、表示される情報のみであり、値は同じです。
list フォーマットと detail フォーマットは、どのエレメント・タイプにも使用できます。list フォーマットは、項目の表に表示されるような要約情報を提供します。detail フォーマットは、より詳細な情報を提供します。このフォーマットには、しばしば関連エレメントの内容が含まれます。一部のエレメントの場合、これらのフォーマットは全く同じです。さらに、name プロパティーを持つエレメント・タイプは、name フォーマットも持っています。このフォーマットには、id プロパティーと name プロパティーのみが含まれています。これは、名前で選択するために項目リストを表示する際に有用な場合があります。便宜のために、エレメント・タイプの name フォーマットは、タイプの最上位 URL に name を付加することによっても作成できます (例えば、GET http://base_url/applications/name)。
作成操作または更新操作の入力として JSON データを提供する時、REST API は、エレメントへの書き込みが可能なプロパティーのみを考慮します。API は他のすべてのデータを無視します。読み取り専用プロパティー (計算されたカウントや作成日など) は更新されません。API は、認識されないプロパティーを無視します。参照を確立するために使用される id プロパティーを除き、関連エレメントのプロパティーも更新されません。
{
"name": "New Release",
"team": {
"id": "00000000-0000-0000-0000-000000000206",
"name": "Not the actual Team name" },
"lifecycleModel": "00000000-0000-0000-0000-000000000006",
"totalChanges": 42,
"BadProperty": "xxxx"
}{
"name": "New Release",
"team": "00000000-0000-0000-0000-000000000206",
"lifecycleModel": "00000000-0000-0000-0000-000000000006"
}同様に、既存のエレメントを更新すると、API は、JSON 入力に指定されたプロパティーのみを変更します。API は、省略されたプロパティーは変更しません。プロパティーの値をクリアするには、そのプロパティーに対して、明示的な JSON ヌル値を指定します。
{
"id": "00000000-0000-0000-0000-123456789000",
"name": "New Feature",
"description": "",
"status": "In Progress",
"type": {
"id":"00000000-0000-1201-0000-000000000001",
"name":"Feature",
"icon":"feature"}
}{
"id": "00000000-0000-0000-0000-123456789000",
"release": "00000000-0000-0000-0000-000000000036"
}{
"id": "00000000-0000-0000-0000-123456789000",
"release": null
}{
"id": "00000000-0000-0000-0000-123456789000",
"release": "00000000-0000-0000-0000-000000000036"
}{
"id": "00000000-0000-0000-0000-123456789000",
"release": {"id":"00000000-0000-0000-0000-000000000036"}
}{
"id": "00000000-0000-0000-0000-123456789000",
"release": {
"id":"00000000-0000-0000-0000-000000000036",
"name":"Sample Release"}
}{
"id": "00000000-0000-0000-0000-123456789000",
"release": {
"id":"00000000-0000-0000-0000-000000000036",
"name":"Not the actual Release name"}
}ただし、他の場合、特にエレメントに特定の関係が必要な場合は、関係の単一値サイドに対する入力を指定することができます。例えば、1 つのアプリケーションを複数のチームに関連付けることができます。この場合は、アプリケーションを作成する時に、「teams」プロパティーに対して UUID ストリングの JSON 配列を提供することができます。この関係を操作するための特別な URL はありません。
エレメント・タイプの中には、静的に定義されたプロパティーに加え、フリー・フォームのキー値ペアの保管および取得をサポートしているものがあります。このタイプのプロパティーは、しばしば、統合プロバイダーにリンクされているデータを表します。例えば、IBM Rational® Team Concert ワークアイテムを表す変更は、そのワークアイテムの ID を、このキー値ストレージ内にプロパティーとして保管する可能性があります。
{
"id": "00000000-0000-0000-0000-123456789000",
"name": "New Feature",
"description": "",
"status": "In Progress",
"type": {
"id":"00000000-0000-1201-0000-000000000001",
"name":"Feature",
"icon":"feature"},
"properties": {
"first":"first value",
"second":"second value",
"third":"third value"}
}いくつかのエレメント・タイプでは、最上位 GET 要求は、フル・リストではなく、エレメントのサブセットを提供することができます。このようなエレメントのサブセットの取得は、一般的に「ページ編集」と呼ばれます。その理由は、各要求で単一「ページ」のデータのみのロードが行われるためです。
照会パラメーターまたは HTTP Range ヘッダーのいずれかを使用して、2 つの代替ページング・フォームが使用可能です。
ページ編集に照会パラメーターを使用するには、rowsPerPage 照会パラメーターと pageNumber 照会パラメーターの両方を HTTP GET 要求に指定します。最初のページを取得するには、コード pageNumber=1 を指定します。例えば、最初の 5 つのアプリケーションを取得するには、要求 GET http://base_url/applications/?rowsPerPage=5&pageNumber=1 を使用します。
Range: items=0-4Content-Range: 0-4/10Content-Range: 0-2/3最上位 GET 操作の結果をソートするには、orderField パラメーターと sortType パラメーターを指定します。orderField パラメーターは、ソートに使用する単一プロパティーの名前を含んでいる必要があります。sortType パラメーターは、昇順でソートするための値 asc か、降順でソートするための値 desc を含んでいる必要があります。
関連エレメントのプロパティーでソートを実行するには、ドット付きパス・フォーマットでプロパティー名を指定します。例えば、関連付けられたリリースに従って変更リストをソートするには、値 release.name を指定します。このパス内のいずれかのプロパティーがヌルの場合、順序付けは不特定なものになります。
GET http://base_url/changes/?format=detail&rowsPerPage=5&
pageNumber=1&orderField=release.name&sortType=asc GET http://base_url/releases/
?filterFields=dateCreated
&filterType_dateCreated=gt
&filterClass_dateCreated=Long
&filterValue_dateCreated=1421171883574
&orderField=dateCreated
&sortType=ascfilterFields=dateCreated&filterFields=name