HTTP
APIのHTTP

Android Angular 2 AngularJS C# Language HTML Java Language JavaScript Node.js PHP Python Language
サーチ…


備考

HTTP APIは広範囲のHTTP動詞を使用し、通常はJSONまたはXML応答を返します。

リソースを作成する

リソース作成の最も意味論的に正しい方法が何であるかについて誰もが同意するわけではありません。したがって、APIはPOST要求またはPUT要求を受け入れることができます。

リソースが正常に作成された場合、サーバーは201 Created応答する必要があります。最も適切なエラーコードを選択します。

たとえば、従業員レコードを作成するAPIを提供する場合、要求/応答は次のようになります。 

POST /employees HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Charlie Smith",
    "age": 38,
    "job_title": "Software Developer",
    "salary": 54895.00
}

HTTP/1.1 201 Created
Location: /employees/1/charlie-smith
Content-Type: application/json

{
    "employee": {
        "name": "Charlie Smith",
        "age": 38,
        "job_title": "Software Developer",
        "salary": 54895.00
        "links": [
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "self",
                "method": "GET"
            },
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "delete",
                "method": "DELETE"
            },
            {
                "uri": "/employees/1/charlie-smith",
                "rel": "edit",
                "method": "PATCH"
            }
        ]
    },
    "links": [
        {
            "uri": "/employees",
            "rel": "create",
            "method": "POST"
        }
    ]
}

レスポンスにlinks JSONを含めることで、クライアントはURIやメソッドを事前に知らなくても、新しいリソースやアプリケーション全体に関連するリソースにアクセスできます。

リソースを編集する

リソースの編集や更新は、APIの共通の目的です。 POST 、 PUTまたはPATCH要求をそれぞれのリソースに送信することによって、編集を行うことができます。 POSTでは、リソースの既存の表現にデータを追加することが許可されていますが、 PUTまたはPATCHどちらかを使用することを推奨します。これは、より明示的な意味を伝えるためです。

サーバーは、更新が実行された場合は200 OK 、まだ適用されていない場合は202 Accepted応答する必要があります。完了できない場合は、最も適切なエラーコードを選択します。

完全な更新

PUTは、現在の表現を要求に含まれるペイロードに置き換えるセマンティクスがあります。ペイロードが、更新すべきリソースの現在の表現と同じ表現型でない場合、サーバはどのアプローチをとるかを決定することができる。 RFC7231は、サーバが

  • 新しいメディアタイプを反映するようにターゲットリソースを再設定する
  • 新しいリソース状態として保存する前に、PUT表現をリソースの形式と一致する形式に変換します
  • ターゲットリソースが特定の（セットの）メディアタイプに限定されていることを示す415 Unsupported Media Typeレスポンスで要求を拒否します。

次のようなJSON HAL表現を含むベースリソース

{
    "name": "Charlie Smith",
    "age": 39,
    "job_title": "Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    }
}

...このような更新要求を受け取ることがあります

PUT /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 85
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer"
}

サーバーはリソースの状態を指定されたリクエスト本体に置き換え、コンテンツタイプをapplication/hal+jsonからapplication/jsonか、JSONペイロードをJSON HAL表現に変換してから、リソースの内容を置き換えます415 Unsupported Media Type応答を持つ不可能なメディアタイプのために、変換されたものと更新要求を拒否する。

コンテンツを直接置き換えるか、または表現を定義済みの表現モデルに変換してから、既存のコンテンツを変換済みの表現モデルに置き換えるかの違いがあります。後続のGET要求は、直接置換で次の応答を返します。 

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer"
}

変換してからアプローチを置換すると、次の表現が返されます。 

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: e0023aa4e

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    }
}

副作用

PUTは、冪等の操作として定義されていますが、副作用があることに注意してください。これはRFC7231で文書化されています。

ターゲット・リソースに適用されるPUT要求は、他のリソースに副作用をもたらす可能性があります。例えば、ある特定のバージョン（特定の時点で現在のバージョンリソースと同じ状態を共有している異なるリソース）を識別するURIとは別の「現在のバージョン」（リソース）を識別するためのURIをアーティクルに含めることができます。したがって、現在のバージョンのURIに対するPUTリクエストが成功すると、ターゲットリソースの状態を変更するだけでなく、新しいバージョンのリソースが作成され、関連リソース間にリンクが追加される可能性があります。

追加のログエントリを作成することは、通常、一般的にリソースの状態がないため、通常は副作用とはみなされません。

部分的な更新

RFC7231では部分的な更新に関してこれについて言及しています：

部分的に更新されたリソースを、より大きなリソースの一部と重なる状態でターゲティングするか、部分的な更新（たとえば、 RFC5789で定義されているPATCHメソッド）のために特別に定義された別の方法を使用して、

したがって、部分的な更新は2つの味で実行できます。

オーバーラップ状態の部分更新

ユーザを他の場所に移動させるためにユーザ表現が部分的に更新される必要がある場合、ユーザを直接更新するのではなく、ユーザ表現の部分的更新に反映される関連資源を直接更新する必要がある。

移動の前に、ユーザは以下の表現を有していた

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    },
    "_embedded": {
        "ea:address": {
            "street": "Terrace Drive, Central Park",
            "zip": "NY 10024"
            "city": "New York",
            "country": "United States of America",
            "_links": {
                "self": { "href": "/address/abc" },
                "google_maps": { "href": "http://maps.google.com/?ll=40.7739166,-73.970176" }
            }
        }
    }
}

ユーザーは新しい場所に移動しているので、次のような彼女の位置情報を更新します。 

PUT /address/abc HTTP/1.1
Host: http://www.acmee.com
Content-Type: "application/json; charset=utf-8"
Content-Length: 109
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)

{
    "street": "Standford Ave",
    "zip": "CA 94306",
    "city": "Pablo Alto",
    "country": "United States of America"
}

上述したように、既存のアドレスリソースと要求内のアドレスとの間のミスマッチメディアタイプの置換前変換セマンティクスにより、アドレスリソースが更新され、ユーザリソースに対する後続のGETリクエストユーザーの新しいアドレスが返されます。 

GET /users/1234 HTTP/1.1
Host: http://www.acmee.com
Accept: application/hal+json; charset=utf-8
Accept-Encoding: gzip, deflate
Accept-Language: en-us
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
ETag: "e0023aa4e"

{
    "name": "Charlie Gold-Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "_links": {
        "self": { "href": "/users/1234" },
        "employee": { "href": "http://www.acmee.com" },
        "curies": [{ "name": "ea", "href": "http://www.acmee.com/docs/rels/{rel}", templated": true}],
        "ea:admin": [
            "href": "/admin/2",
            "title": "Admin"
        ]
    },
    "_embedded": {
        "ea:address": {
            "street": "Standford Ave",
            "zip": "CA 94306",
            "city": "Pablo Alto",
            "country": "United States of America"
            "_links": {
                "self": { "href": "/address/abc" },
                "google_maps": { "href": "http://maps.google.com/?ll=37.4241311,-122.1524475" }
            }
        }
    }
}

部分データへのパッチ適用

PATCHはRFC5789で定義されており、HTTP仕様自体の一部ではありません。一般的な誤解は、 部分的に更新する必要があるフィールドのみを送信することは 、 PATCH要求で十分であるということです。従って、仕様書は

PATCHメソッドは、要求エンティティに記述された一連の変更がRequest-URIによって識別されるリソースに適用されることを要求します。変更のセットは、メディアタイプによって識別される「パッチドキュメント」と呼ばれるフォーマットで表されます。

つまり、クライアントは、リソースを状態Aから状態Bに変換し、これらの命令をサーバーに送信するために必要なステップを計算する必要があります。

人気のJSONベースのメディアタイプのパッチはJSONパッチです。

サンプルユーザーの年齢と役職が変更され、ユーザーの所得を表す追加フィールドを追加する必要がある場合、JSONパッチを使用してPATCHを使用して部分的に更新すると、次のようになります。 

PATCH /users/1234 HTTP/1.1
Host: http://www.acmee.com
Content-Type: application/json-patch+json; charset=utf-8
Content-Length: 188
Accept: application/json
If-Match: "e0023aa4e"

[
    { "op": "replace", "path": "/age", "value": 40 },
    { "op": "replace", "path": "/job_title", "value": "Senior Software Developer" },
    { "op": "add", "path": "/salery", "value": 63985.00 }
]

PATCHは一度に複数のリソースを更新し、すべての変更を適用する必要があるか、API実装者にトランザクション上の負担をかけることがないかのいずれかを意味する変更をアトミックに適用する必要があります。

更新が成功すると、次のようなものが返されます

HTTP/1.1 200 OK
Location: /users/1234
Content-Type: application/json
ETag: "df00eb258"

{
    "name": "Charlie Smith",
    "age": 40,
    "job_title": "Senior Software Developer",
    "salary": 63985.00
}

200 OK応答コードのみに限定されるものではありません。

中間の更新（以前の表現状態のフェッチと更新の間で行われた変更） ETag 、 If-MatchまたはIf-Unmodified-Sinceヘッダーを使用する必要があります。

エラー処理

PATCHの仕様では、次のエラー処理を推奨しています。

タイプエラーコード
不正な形式のパッチ文書 400 Bad Request
サポートされていないパッチドキュメント 415 Unsupported Media Type
処理不能な要求、つまりパッチを適用してresoureが無効になった場合 422 Unprocessable Entity
リソースが見つかりません 404 Not Found
競合状態、すなわち、存在しないフィールドの名前の変更（移動） 409 Conflict
競合する変更、つまり、クライアントが検証が失敗したIf-MatchまたはIf-Unmodified-Sinceヘッダーを使用しているIf-Match前提条件がない場合は、後者のエラーコードを返す必要があります 412 Precondition Failedまたは409 Conflict
並行変更、すなわち、要求が受理前に適用される必要がある場合、さらなるPATCH要求 409 Conflict

リソースを削除する

HTTP APIの別の一般的な使用方法は、既存のリソースを削除することです。これは、通常、 DELETE要求を使用して行う必要があります。

削除が成功した場合、サーバーは200 OKを返します。そうでなければ適切なエラーコード。

従業員チャーリー・スミスが退社してレコードを削除したい場合は、次のようになります。 

DELETE /employees/1/charlie-smith HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    'links': [
        {
            'uri': '/employees',
            'rel': 'create',
            'method': 'POST'
        }
    ]
}

リソースを一覧表示する

HTTP APIの最後の一般的な使用方法は、サーバー上の既存のリソースのリストを取得することです。このようなリストは、 GETリクエストを使用して取得する必要がありますGETリクエストはデータを取得するためです。

サーバーは、リストを提供できる場合は200 OK 、そうでない場合は適切なエラーコードを返す必要があります。

従業員をリストすると、次のようになります。 

GET /employees HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
    'employees': [
        {
            'name': 'Charlie Smith',
            'age': 39,
            'job_title': 'Software Developer',
            'salary': 63985.00
            'links': [
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'self',
                    'method': 'GET'
                },
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'delete',
                    'method': 'DELETE'
                },
                {
                    'uri': '/employees/1/charlie-smith',
                    'rel': 'edit',
                    'method': 'PATCH'
                }
            ]
        },
        {
            'name': 'Donna Prima',
            'age': 30,
            'job_title': 'QA Tester',
            'salary': 77095.00
            'links': [
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'self',
                    'method': 'GET'
                },
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'delete',
                    'method': 'DELETE'
                },
                {
                    'uri': '/employees/2/donna-prima',
                    'rel': 'edit',
                    'method': 'PATCH'
                }
            ]
        }
    ],
    'links': [
        {
            'uri': '/employees/new',
            'rel': 'create',
            'method': 'PUT'
        }
    ]
}


Modified text is an extract of the original Stack Overflow Documentation
ライセンスを受けた CC BY-SA 3.0
所属していない Stack Overflow