「このAPIのこのバージョンは廃止されました」の正しいHTTPステータスコードは何ですか？
RESTful APIがあります。それには3つのバージョンがあります：v1、v2、およびv3。 v4を公開しようとしています。v1を廃止することにしました。つまり、http://example.com/v1/resourceへのすべてのリクエストは失敗しますが、http://example.com/v2/resourceへの呼び出しは引き続き機能します。
失敗を示す適切な方法は何ですか？ 410 GONEステータスコードの使用を検討しましたが、それはリソースが使用できなくなったことを示しています。リソースはおそらくISまだ利用可能ですが、異なる方法でのみ要求する必要があります。
汎用の400ステータスコードも検討しましたが、それも奇妙に思えました。これに対する標準的な回答はありますか？
標準はないようです。
StackOverflow answer は410 GONEに傾いていますが、301 MOVED PERMANENTLYの方が適切だと思います。
正しい選択をするために、特定のケースを調べる必要があります。 API v1に対して行われたすべての呼び出しを、それ以上のアクションを実行せずに失敗させることが目標である場合、410 GONEはそのために機能します。呼び出しが成功する可能性があるAPIの新しいバージョンにクライアントをリダイレクトするなど、継続性が必要な場合、3XXは機能しますが、どちらを選択しますか？ API v1をシャットダウンしようとしている場合、301 MOVED PERMANENTLYが303 SEE OTHERよりも優れていることを示すのに役立ちます。301は、将来のすべてのリクエストを新しいURLに対して行う必要があることを示唆するのに対し、303はこの状況が永久的。
各バージョンが後方互換性を維持するように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応答は、Originサーバーがサーバーによって転送できるターゲットリソースの表現を持っていないことを示しますHTTP経由。ただし、Locationフィールドの値は、ターゲットリソースを説明するリソースを参照するため、他のリソースで取得要求を行うと、元のターゲットリソースを表すことを意味することなく、受信者にとって有用な表現になる可能性があります。
410 GONE-410（Gone）ステータスコードは、Originサーバーでターゲットリソースへのアクセスができなくなり、この状態が発生する可能性が高いことを示します。恒久的であること。 Originサーバーが条件が永続的であるかどうかを知らない、または判断する機能がない場合、代わりにステータスコード404（Not Found）を使用する必要があります。
既存のAPIはこれをどのように処理しますか？
Googleの Youtube API からページを取得できます。
APIリクエストが失敗すると、YouTubeは失敗を一般的に識別するHTTP 4xxまたは5xx応答コードと、失敗の原因となったエラーに関するより具体的な情報を提供するXML応答を返します。各エラーのXML応答には、ドメイン要素、コード要素、および場合によっては場所要素が含まれます。
- BigCommerce API は302 FOUNDを使用します。
- アトラシアンREST APIガイドライン 301 MOVED PERMANENTLYのヒントと、エラーを詳細に説明するサブコード。これはYoutube APIのアプローチに似ています。
参考文献：
リダイレクトは、移動したリソースに最適です。 301の永続的なリダイレクト（APIを変更せずに名前を変更することを示す）の代わりに、303 "See Other"リダイレクトを使用します。
リダイレクトなしでレガシーを引き続きサポートする必要がありますか？たとえあなたがまだそれをサポートしていて、それが深く実装されているとしても、501はむしろあなたの状況と密接に関連しているように見えます。知識のある人はまだそれを使用できますが、ランダムはv1の501を見るでしょう。
10.5.2 501実装されていません
サーバーは、要求を満たすために必要な機能をサポートしていません。これは、サーバーが要求メソッドを認識せず、どのリソースに対しても要求メソッドをサポートできない場合の適切な応答です。
サービスが利用できないというメッセージで503を使用し、新しいバージョンを使用することを示します。このメッセージは、コールの50％に対して返され、徐々に100％に増加します。
透過的な移行では、 8 -301とは異なり、このメソッドは動詞を変更しないため（POSTはPOST）、永続リダイレクトを使用します。