Web APIの適切なリターン

Question

私は、単一のオブジェクトを返すASP.NETコアコントローラを持っています。このオブジェクトは/ class、Person型のものです。あなたはAPI関数を呼び出します。質問は人の名前を表す単一のパラメータをとります。だから、APIの目的はひとりの人を名前で返すことです。人が見つからない場合、ベストプラクティスの返品は何ですか？私はnullを返す必要がありますか？私は戻って/例外をスローする必要がありますか？

return new ObjectResult(person); 
return NotFound(); // NotFound() is framework function - returns 404 

「Not Found」は、一般的に、リソース自体が見つからないことをHTTPで意味すると心配しています。 「Can/should Not Found」は、照会されたオブジェクトが見つからなかったことを意味するのにも使用できますか？

Answer 1

これを行う適切な方法は、HTTP 404ステータスコードを返すことです。

人物はあなたのAPIのコンテキスト内のリソースなので、問題はないはずです。 RESTのクライアントと開発者はHTTPエラーをどのように処理するかを知っており、404エラーは非常に意味があります。

404レスポンスボディに理由を書き込むことはできますが、気にしません。

REST APIレスポンスのHTTPステータスコードの使用をさらに拡張するために、特定のDepartmentの従業員をのように1つのオブジェクトではなくセットを返すと、HTTP 204部門が存在しても従業員が存在しない場合（既存部門の空集合を意味する）、またはその部門が存在しない場合はHTTP 404（NOT FOUND）ステータスである。 APIと返されるステータスコードの意味を常に文書化する必要があります。

---

このアプローチのもう1つの方法は、成功/エラー情報とペイロードを含む標準化されたJSON応答を作成することです。人はこのようなものを使用できreturns

public class ApiResponse { 
    // I use lowercase properties so that the JSON follows common JavaScript naming conventions 
    public bool success { get; set; } 
    public String errorMessage { get; set; } 
    public int? errorCode { get; set; } 
} 

そして、あなたのコントローラの方法：たとえば、すべてのコントローラの「JSON」アクションは、このベースクラッセから継承するクラス返すことができて

public class GetPersonResponse : ApiResponse { 
    public PersonModel person { get; set; } 
} 

をごコントローラは、あなたがこのような何かを行うことができ：JSONシリアライザがnullのプロパティ（デフォルトでは）シリアライズしませんので

public GetPersonResponse Person(string id) { 
    var person = FindPersonByName(id); 
    var response = new GetPersonResponse { 
     success = person != null, 
     person = person 
    } 
    if (person == null) { 
     response.errorCode = 404, // suggestion only 
     response.errorMessage = "Person not found" 
    }   
    return response; 
} 

上記のコードは、あなたがいないセリアによってカバーされますペイロード（人物）が見つからない場合にはその人物をライジングし、そうであればエラー情報をシリアライズしない。