9

RESTful APIでHTTPステータスコードを返すためのベストプラクティスは何ですか？PHPフレームワークにLaravel4を使用しています。

エラーの場合、私は使用する必要があります

return Response::json('User Exists', 401);

また

のフラグを含めるsuccess

return Response::json([
    'success' => false,
    'data' => 'User Exists'],
    401
);

また

successエラーがあるかどうかを判断するために、4xxの代わりに200を使用します

return Response::json([
    'success' => false,
    'data' => 'User Exists'],
    200
);

そして、成功してデータを返す必要がない場合でも、何かを返しますか？

PHPAPIコード

public function getCheckUniqueEmail() {
    // Check if Email already exist in table 'users'
    $uniqueEmail = checkIfEmailExists();

    // Return JSON Response
    if($uniqueEmail) {
        // Validation fail (user exists)
        return Response::json('User Exists', 401);
    } else {
        // Validation success
        // - Return anything?
    }
}
4

3 に答える 3

12

利用可能なHTTPステータスコードのリストを見ると、ある時点でそれらがたくさんあることに気付くでしょうが、単独で使用すると、それ自体ではエラーを実際に説明することはできません。

それであなたの質問に答えるために、2つの部分があります。1つは、APIがエラーの理由をどのように伝え、APIのユーザー（ほとんどの場合、別の開発者）が読み取って操作できる有用な情報を追加できるかです。機械可読と人間可読の両方で、できるだけ多くの情報を追加する必要があります。

他の部分：HTTPステータスコードは、特定のエラー（および成功）状態を区別するのにどのように役立ちますか？

この後者の部分は、実際には1つよりも難しいです。404が「見つからない」ことを示すために使用される明らかなケースがあります。サーバー側のエラーの場合は500。

HTTP認証クレデンシャルが存在する場合に操作を成功させたい場合を除いて、ステータス401は使用しません。401は通常、ブラウザでダイアログボックスをトリガーしますが、これは悪いことです。

リソースが一意であり、すでに存在している場合は、ステータス「409競合」が適切と思われます。また、ユーザーの作成が成功した場合は、ステータス「201作成済み」も良い考えのように思えます。

ステータスコードはもっとたくさんあることに注意してください。そのうちのいくつかはHTTPプロトコルの拡張に関連しており（DAVなど）、完全に標準化されていないものもあります（TwitterAPIのステータス「420Enhanceyourcalm」など）。http://en.wikipedia.org/wiki/List_of_HTTP_status_codesを見て、これまでに使用されたものを確認し、エラーの場合に適したものを使用するかどうかを決定してください。

私の経験から、ステータスコードを選択して使用するのは簡単ですが、一貫して既存の標準に従って行うのは困難です。

しかし、他の人が不平を言うかもしれないという理由だけで、私はここで止まりません。:) RESTfulインターフェースを正しく実行すること自体は難しい作業ですが、存在するインターフェースが多いほど、より多くの経験が収集されています。

編集：

バージョニングについて：次のように、URLにバージョンタグを付けるのは悪い習慣と考えられています：example.com/api/v1/stuffそれは機能しますが、良くありません。

しかし、最初に重要なことは、クライアントが取得したい表現の種類をどのように指定するか、つまり、JSONまたはXMLのどちらを取得するかをどのように決定できるかということです。回答：Acceptヘッダー付き。彼はAccept: application/jsonJSONとAccept: application/xmlXMLを送信できました。彼は複数のタイプを受け入れるかもしれません、そしてそれはサーバーがそれから何を返すかを決定することです。

サーバーがリソースの複数の表現（JSONまたはXML、クライアント選択）で応答するように設計されていない限り、クライアントにとって実際には多くの選択肢はありません。ただし、クライアントに少なくとも「application / json」を唯一の選択肢として送信させ、それContent-type: application/jsonに応じてヘッダーを返すようにすることは、依然として良いことです。このようにして、双方は、相手がコンテンツをどのように見ることを期待しているのかを明確にします。

今バージョンのために。バージョンをURLに入れると、効果的に異なるリソース（v1とv2）が作成されますが、実際には、アクセスする方法が異なる1つのリソース（= URL）しかありません。APIの新しいバージョンの作成は、現在のバージョンと互換性のない要求および/または応答の表現に重大な変更があった場合に実行する必要があります。

したがって、JSONを使用するAPIを作成する場合、汎用JSONは処理しません。APIに何らかの形で固有の具体的なJSON構造を扱います。Content-typeサーバーからの送信でこれを示すことができ、おそらく示す必要があります。これには「ベンダー」拡張機能があります。Content-type: application/vnd.IAMVENDOR.MYAPI+json基本的なデータ構造はapplication/jsonであることを世界に知らせますが、実際にどの構造を期待するかを指示するのは会社とAPIです。そして、それはまさにAPIリクエストのバージョンが適合する場所です：application/vnd.IAMVENDOR.MYAPI-v1+json。

したがって、URLにバージョンを入れる代わりに、クライアントがAccept: application/vnd.IAMVENDOR.MYAPI-v1+jsonヘッダーを送信することを期待し、同様に応答しContent-type: application/vnd.IAMVENDOR.MYAPI-v1+jsonます。これは最初のバージョンでは実際には何も変わりませんが、バージョン2が登場したときに状況がどのように発展するかを見てみましょう。

URLアプローチでは、まったく関係のない新しいリソースのセットが作成されます。example.com/api/v2/stuffクライアントは、がと同じリソースであるかどうか疑問に思いますexample.com/api/v1/stuff。クライアントはv1APIを使用していくつかのリソースを作成し、このようなもののURLを保存した可能性があります。彼はこれらすべてのリソースをv2にどのようにアップグレードすることになっていますか？リソースは実際には変更されていません。同じです。変更されたのは、v2では外観が異なることだけです。

はい、サーバーはv2URLへのリダイレクトを送信してクライアントに通知する場合があります。ただし、リダイレクトは、クライアントがAPIのクライアント部分もアップグレードする必要があることを示すものではありません。

バージョンでacceptヘッダーを使用する場合、リソースのURLはすべてのバージョンで同じです。クライアントはバージョン1または2のいずれかでリソースを要求することを決定し、サーバーは非常に親切で、バージョン1の要求にバージョン1の応答で応答しますが、すべてのバージョン2の要求は新しくて光沢のあるバージョン2の応答で応答します。

サーバーがバージョン1の要求に応答できない場合、サーバーはHTTPステータス「406Not Acceptable」を送信することでクライアントに通知できます（要求されたリソースは、要求で送信されたAcceptヘッダーに従って受け入れられないコンテンツのみを生成できます）。

クライアントは、両方のバージョンが含まれているacceptヘッダーを送信できます。これにより、サーバーは最も気に入ったバージョンで応答できるようになります。つまり、スマートクライアントは、バージョン1と2を実装し、両方をacceptヘッダーとして送信し、サーバーがアップグレードするのを待ちます。バージョン1から2まで。サーバーはすべての応答でバージョン1か2かを通知し、クライアントはそれに応じて動作できます。サーバーのバージョンアップグレードの正確な日付を知る必要はありません。

要約すると、非常に基本的なAPIの場合、バージョンが限られていても、おそらく内部的な使用法はやり過ぎかもしれません。しかし、これが1年後に真実になるかどうかはわかりません。APIにバージョン番号を含めることは常に非常に良い考えです。そして、これに最適な場所は、APIが使用しようとしているmimeタイプの内部です。単一の既存のバージョンをチェックするのは簡単なはずですが、既存のクライアントを混乱させることなく、後で透過的にアップグレードするオプションがあります。

于 2013-03-24T15:47:54.847 に答える
2

すべてに200ステータスを使用するわけではありません。それは混乱を招くでしょう。

Jqueryを使用すると、さまざまな応答コードをさまざまに処理できます。そのためのメソッドがすでに組み込まれているため、アプリでそれらを使用できます。アプリが大きくなったときに、他のユーザーも使用できるようにそのAPIを提供できます。

編集：また、LaravelとAPI開発についてのこの講演を見ることを強くお勧めします：

http://kuzemchak.net/blog/entry/laracon-slides-and-video

于 2013-03-24T16:27:50.240 に答える
1

Illuminate\Http\Responseに拡張されたHTTPステータスコードのリストがいくつかありますSymfony\Component\HttpFoundation\Response。あなたはあなたのクラスでそれを使うことができます。

例えば：

use Illuminate\Http\Response as LaravelResponse;
...
return Response::json('User Exists', LaravelResponse::HTTP_CONFLICT);

それははるかに読みやすいです。

于 2014-03-12T15:05:12.187 に答える