ペイロード構造の標準化

全エンドポイント共通の情報の標準化

データエンベロープは、JSON をラップするラッパーであり、システム API との間で送受信されます。標準のペイロード構造を維持するために、システム API では、DataEnvelope と DataListEnvelope の 2 つのデータエンベロープを使用します。

DataEnvelope を使用して、単一要素の情報の形式を標準化します。data プロパティを次のプロパティで指定します。対象プロパティは、checksum、id、links（単一要素）、method、refid、related、type、および uri です。概要レベルでは、単一要素のペイロードの形式は以下のようになります。

{
    "data": {
        "checksum": ...,
        "id":       ...,
        "links":    ...,
        "method":   ...,
        "refid":    ...,
        "related":  ...,
        "type":     ...,
        "uri":      ...
        }
    }
}

DataListEnvelope を使用して、コレクション情報の形式を標準化します。データセクションと兄弟関係にある以下のプロパティを指定します。 count、links（コレクション）、および total プロパティを指定します。概要レベルでは、単一要素のペイロードの形式は以下のようになります。

{
    "count"    ...,
    "data": [
        { properties_for_element_1 },
        { properties_for_element_2 },
        ...
    ],
    "links":   ...,
    "total":   ...
}

各プロパティが各ペイロードに表示されるとは限りません。プロパティが特定のペイロードに表示されない場合の理由はさまざまです。例：

• refid などのプロパティは要求にのみ適用され、応答ペイロードには表示されません。
• count などのプロパティは応答にのみ適用され、要求ペイロードには表示されません。
• related などのプロパティはデフォルトでは表示されず、要求に特定のクエリパラメータが含まれる場合にのみ表示されます。

特定のエンドポイント固有情報の標準化

DataEnvelope と DataListEnvelope で用意している標準形式の情報は、すべての要求ペイロードと応答ペイロードに適用可能です。ただし、さまざまなエンドポイントがさまざまな種類のリソースとやりとりを行います。各エンドポイントで、ペイロードの一部が特定の種類のリソースについての情報を提供する必要があります。

これに対処するため、システム API では要求スキーマと応答スキーマも使用します。要求スキーマは、有効な構造の定義に使用されるスキーマであり、特定セットのエンドポイントの要求ペイロードで有効な構造です。同様に、応答スキーマは、有効な構造の定義に使用されるスキーマであり、特定セットのエンドポイントの応答ペイロードで有効な構造です。

要求スキーマと応答スキーマは階層化されています。例えば、応答の場合、GET /activity/{activityId} エンドポイントは ActivityResponse スキーマを使用します。このスキーマには、ActivityData と ActivityResponseInclusions の 2 つの子スキーマがあります。

要求スキーマと応答スキーマで DataEnvelope または DataListEnvelope を拡張します。これにより、すべてのエンドポイントに関連する情報が、標準的な方法でペイロードに表示されます。

また、要求スキーマと応答スキーマは、ペイロードの attributes プロパティも定義します。ペイロードのリソース固有情報を含むスキーマにこのプロパティは関連付けられます。例えば、GET /activity/{activityId} エンドポイントで ActivityData 子スキーマの attributes プロパティを指定します。このプロパティは Activity スキーマに関連付けられ、このスキーマには activityPattern や activityType などのアクティビティ固有フィールドが含まれます。その結果、GET /activity/{activityId} エンドポイントの応答ペイロードの構造は以下のようになります。

{
    "data": {
        "checksum": ...,
        "attributes" : {
            "activityPattern": ... ,
            "activityType": ...,
            ...},
        "id":       ...,
        "links":    ...,
        "method":   ...,
        "refid":    ...,
        "related":  ...,
        "type":     ...,
        "uri":      ...
        }
    }
}