「このAPIのこのバージョンは廃止されました」の正しいHTTPステータスコードは何ですか？

RESTful APIを持っています。それには、v1、v2、v3の3つのバージョンがあります。v4を公開しようとしています。v1を中止することにしました。つまり、すべてのリクエストhttp://example.com/v1/resourceは失敗しますが、コールhttp://example.com/v2/resourceは引き続き機能します。

失敗を示す適切な方法は何ですか？410 GONEステータスコードの使用を検討しましたが、それはリソースが使用できなくなったことを示しています。ただし、リソースはまだ使用可能である可能性がありますが、別の方法で要求する必要があります。

また、一般的な400ステータスコードも検討しましたが、それも奇妙に思えました。これに対する標準的な答えはありますか？

標準はないようです。

StackOverflowの回答は 410 GONEに傾いていますが、301 MOVED PERMANENTLYの方が適切だと思います。

正しい選択をするために、特定のケースを調べる必要があります。API v1に対して行われたすべての呼び出しを、それ以上のアクションを実行せずに失敗させることが目標である場合、410 GONEはそのために機能します。呼び出しが成功する可能性があるAPIの新しいバージョンにクライアントをリダイレクトするなど、継続性が必要な場合、3XXは機能しますが、どちらを選択しますか？API v1をシャットダウンしようとしている場合、301 MOVED PERMANENTLYは303 SEE OTHERよりも優れていることを示すのに役立ちます。永久的。

各バージョンが後方互換性を維持するようにAPIを設計することをお勧めします。これにより、新しいAPIバージョンに新しいエンドポイントを追加するたびに、301 MOVED PERMANENTLYが透過的にAPIを常に最新の状態に保ちます。とにかくあなたがやろうとしていることだと思う。

HTTPステータスコード

HTTPステータスコード302はもともと広すぎたため、誤って実装/使用されるようになったため、302のデュアルユースケースを区別するために303と307が作成されました。一部のAPIは、他の目的で303を使用します。

301 MOVED PERMANENTLY -301（Moved Permanently）ステータスコードは、ターゲットリソースに新しい永続URIが割り当てられ、このリソースへの今後の参照では、囲まれたURIのいずれかを使用する必要があることを示します。

302 FOUND -302（Found）ステータスコードは、ターゲットリソースが一時的に別のURIにあることを示します。リダイレクトはときどき変更される可能性があるため、クライアントは今後のリクエストに引き続き有効なリクエストURIを使用する必要があります。

303 SEE OTHER -GETリクエストに対する303レスポンスは、オリジンサーバーがHTTP経由でサーバーによって転送できるターゲットリソースの表現を持っていないことを示します。ただし、Locationフィールドの値は、ターゲットリソースを説明するリソースを参照します。そのため、他のリソースで取得要求を行うと、元のターゲットリソースを表すことを意味することなく、受信者にとって有用な表現になります。

410 GONE -410（Gone）ステータスコードは、ターゲットリソースへのアクセスがオリジンサーバーで使用できなくなり、この状態が永続的である可能性が高いことを示します。オリジンサーバーが条件が永続的かどうかを知らない、または判断する機能がない場合は、代わりにステータスコード404（Not Found）を使用する必要があります。

既存のAPIはこれをどのように処理しますか？

たぶん、GoogleのYoutube APIからページを取得できます：

APIリクエストが失敗すると、YouTubeは失敗を一般的に識別するHTTP 4xxまたは5xx応答コードと、失敗の原因となったエラーに関するより具体的な情報を提供するXML応答を返します。エラーごとに、XML応答には、ドメイン要素、コード要素、および場合によっては場所要素が含まれます。

• BigCommerce APIは302 FOUNDを使用します。
• Atlassian REST APIガイドラインでは、301 MOVED PERMANENTLYとともに、エラーを詳細に説明するサブコードが示されています。これはYoutube APIのアプローチに似ています。

参考文献：

• REST APIはどのようにバージョン管理されますか？
• Netflix APIの設計：トレンドに立ち向かうとき

リダイレクトは、移動したリソースに最適です。301の永続的なリダイレクト（APIを変更せずに名前を変更することを示す）の代わりに、303 "See Other"リダイレクトを使用します。

リダイレクトなしでレガシーを引き続きサポートする必要がありますか？たとえあなたがまだそれをサポートしていて、それが深く実装されているとしても、501はむしろあなたの状況と密接に関連しているように見えます。知識のある人はまだそれを使用できますが、ランダムではv1の501が表示されます。

10.5.2 501実装されていません

サーバーは、要求を満たすために必要な機能をサポートしていません。これは、サーバーが要求メソッドを認識せず、どのリソースに対しても要求メソッドをサポートできない場合の適切な応答です。

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

サービスが利用できないというメッセージで503を使用し、新しいバージョンを使用することを示します。このメッセージは、コールの50％に対して返され、徐々に100％に増加します。

透明な移行のために、私が使用する308 -この方法永久リダイレクトは、301とは異なり（POSTがPOSTであろう）動詞変更しません。