例

このページには、仕様の様々な部分を適用する方法に関する追加の例が含まれています。

スパー スフィールドセット

スパースフィールドセット の動作例。

基本的なリクエスト

GET /articles?include=author HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
        "age": 80,
        "gender": "male"
      }
    }
  ]
}

fields[articles] および fields[people] パラメータを含むリクエスト

GET /articles?include=author&fields[articles]=title,body,author&fields[people]=name HTTP/1.1

注: 上記の例では、読みやすさのためにURIにエンコードされていない[ と ] 文字が表示されています。実際には、基本仕様で述べられているように、これらの文字はパーセントエンコードする必要があります。「パラメータ名における角括弧」を参照してください。

ここでは、articles オブジェクトに title、body、author のフィールドのみを、people オブジェクトに name フィールドのみを含めたいと考えています。

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever."
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John"
      }
    }
  ]
}

(リレーションシップもフィールドであるため)リレーションシップ名をinclude と fields の両方に追加する必要があることに注意してください。それ以外の場合は、以下のようになります。

GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever."
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John"
      }
    }
  ]
}

注: 上記の例では、読みやすさのためにURIにエンコードされていない[ と ] 文字が表示されています。実際には、基本仕様で述べられているように、これらの文字はパーセントエンコードする必要があります。「パラメータ名における角括弧」を参照してください。

ページネーションリンク

ページネーションリンク を追加する方法に関するページベース戦略の例。

基本的なリクエスト

GET /articles?page[number]=3&page[size]=1 HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "meta": {
    "totalPages": 13
  },
  "data": [
    {
      "type": "articles",
      "id": "3",
      "attributes": {
        "title": "JSON:API paints my bikeshed!",
        "body": "The shortest article. Ever.",
        "created": "2015-05-22T14:56:29.000Z",
        "updated": "2015-05-22T14:56:28.000Z"
      }
    }
  ],
  "links": {
    "self": "http://example.com/articles?page[number]=3&page[size]=1",
    "first": "http://example.com/articles?page[number]=1&page[size]=1",
    "prev": "http://example.com/articles?page[number]=2&page[size]=1",
    "next": "http://example.com/articles?page[number]=4&page[size]=1",
    "last": "http://example.com/articles?page[number]=13&page[size]=1"
  }
}

注: 上記の例では、読みやすさのためにURIにエンコードされていない[ と ] 文字が表示されています。実際には、基本仕様で述べられているように、これらの文字はパーセントエンコードする必要があります。「パラメータ名における角括弧」を参照してください。

注: "meta" に "totalPages" のようなプロパティを入れることは、クライアントにコレクションの総ページ数を示す便利な方法です（"last" リンクは最後のページのURIのみを提供します）。ただし、すべての "meta" 値は実装固有であるため、このメンバーを任意の名前（"total"、"count" など）で呼び出すか、まったく使用しないことができます。

エラーオブジェクト

エラーオブジェクト の動作例。

基本的なエラーオブジェクト

以下のレスポンスでは、サーバーはリソースの作成/更新中にエラーが発生し、そのエラーが不正な "firstName" 属性によって発生したことを示しています。

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/firstName" },
      "title":  "Invalid Attribute",
      "detail": "First name must contain at least two characters."
    }
  ]
}

エラーオブジェクトの各メンバーはオプションですが、すべてクライアントに追加の詳細を提供することで役立ちます。

source メンバーは、エラーの原因となったリクエストドキュメントの部分を示すために使用されます。

title と detail メンバーは似ていますが、detail は問題のこの発生に固有のものであるのに対し、title はより一般的なものです。

status メンバーは、問題に関連付けられたHTTPステータスコードを表します。複数のエラーが一度に返される場合（下記参照）、HTTPレスポンス自体には1つのステータスコードしか存在できないため、これは非常に役立ちます。ただし、クライアントがHTTPヘッダーを参照する手間を省いたり、近いうちに正式にサポートされる可能性のある非HTTPプロトコル上でJSON:APIを使用したりする場合にも、単一エラーの場合にも役立ちます。

複数のエラー

単一のリクエストに対して複数のエラーが発生した場合、サーバーは各エラーを errors 配列に追加するだけです。

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "403",
      "source": { "pointer": "/data/attributes/secretPowers" },
      "detail": "Editing secret powers is not authorized on Sundays."
    },
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/volume" },
      "detail": "Volume does not, in fact, go to 11."
    },
    {
      "status": "500",
      "source": { "pointer": "/data/attributes/reputation" },
      "title": "The backend responded with an error",
      "detail": "Reputation service not responding after three requests."
    }
  ]
}

エラーオブジェクトの一意性の制約は、id フィールドのみです。したがって、同じ属性の複数のエラーにそれぞれ独自のエラーオブジェクトを与えることができます。以下の例は、"firstName" 属性の複数のエラーを示しています。

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "source": { "pointer": "/data/attributes/firstName" },
      "title": "Invalid Attribute",
      "detail": "First name must contain at least two characters."
    },
    {
      "source": { "pointer": "/data/attributes/firstName" },
      "title": "Invalid Attribute",
      "detail": "First name must contain an emoji."
    }
  ]
}

注: 上記の422ステータスコードのレスポンスでは、400 Bad Request も許容されます。（詳細はこちら。）JSON:APIは400と422のどちらを採用するかについては立場を表明していません。

エラーコード

エラーオブジェクトの code メンバーには、発生した問題の種類を表すアプリケーション固有のコードが含まれています。code は、どちらも一般的な問題の種類を識別する点でtitle と似ていますが（特定の問題のインスタンスに固有のdetail とは異なります）、ローカリゼーションのために異なる形式で同じtitle が表示される可能性があるため、code を処理する方がプログラム的に簡単です。

以下の例では、APIドキュメントで次のマッピングが指定されているとします。

コード 問題
123 値が短すぎる
225 パスワードに文字、数字、または句読点の文字がありません
226 パスワードが一致しません
227 パスワードは過去5つのパスワードのいずれにすることができません

"password" 属性の複数のエラー、エラーcode 付き

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "jsonapi": { "version": "1.1" },
  "errors": [
    {
      "code":   "123",
      "source": { "pointer": "/data/attributes/firstName" },
      "title":  "Value is too short",
      "detail": "First name must contain at least two characters."
    },
    {
      "code":   "225",
      "source": { "pointer": "/data/attributes/password" },
      "title": "Passwords must contain a letter, number, and punctuation character.",
      "detail": "The password provided is missing a punctuation character."
    },
    {
      "code":   "226",
      "source": { "pointer": "/data/attributes/password" },
      "title": "Password and password confirmation do not match."
    }
  ]
}

このレスポンスには、最上位レベルの errors メンバーだけでなく、最上位レベルの jsonapi メンバーも含まれていることに注意してください。エラーレスポンスには最上位レベルの data メンバーを含めることはできませんが、JSON:APIで定義されている他のすべての最上位レベルのメンバーを含めることができます。

また、3番目のエラーオブジェクトにdetail メンバーがないことにも注意してください（おそらくセキュリティのため）。繰り返しになりますが、すべてのエラーオブジェクトメンバーはオプションです。

拡張された source の使用

以下の例では、ユーザーはdata メンバーがないため、無効なJSON:APIリクエストを送信しています。

PATCH /posts/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{ "datum": [ ] }

そのため、サーバーは次のように応答します。

HTTP/1.1 422 Unprocesssable Entity
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "source": { "pointer": "" },
      "detail":  "Missing `data` Member at document's top level."
    }
  ]
}

これはsource を使用してドキュメントの最上位レベル("")を指します。(リクエストドキュメント{"": "some value"}内の文字列"some value"への適切な参照は「/」を指すでしょう。"/data"を指すのは無効です。なぜなら、リクエストドキュメントには"/data"に値がなく、sourceは常にリクエストドキュメントを参照して与えられるからです。)

サーバーがリクエストを有効なJSONとして解析できない場合、source を含めることは意味がありません（source が参照するJSONドキュメントがないため）。無効なJSONドキュメントに対するサーバーの応答方法を次に示します。

{
  "errors": [{
    "status": "400",
    "detail": "JSON parse error - Expecting property name at line 1 column 2 (char 1)."
  }]
}

無効なクエリパラメータ

source メンバーは、次のように、エラーがURIクエリパラメータの問題に由来することを示すためにも使用できます。

GET /api/posts/1?include=author HTTP/1.1

HTTP/1.1 400 Bad Request
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "source": { "parameter": "include" },
      "title":  "Invalid Query Parameter",
      "detail": "The resource does not have an `author` relationship path."
    }
  ]
}

ほとんどの場合、JSON:APIでは、JSON:APIで定義されたクエリパラメータの無効な値が発生したときに、サーバーがエラーを返す必要があります。ただし、API固有のクエリパラメータ（つまり、JSON:APIで定義されていないもの）の場合、サーバーは、エラーで応答するのではなく、無効なパラメータを無視してリクエストを成功させることができます。API固有のクエリパラメータには、a〜z以外の文字を1つ含める必要があります。

無効なパラメータの他の例としては、?fields[people]=（無効なパラメータ名。 fields[people]にする必要があります）や?redirect_to=http%3A%2F%2Fwww.owasp.org（無効なパラメータ、この場合はフィッシング攻撃）などがあります。