現在,當談論起 RESTful Web API 的時候,人們總會想到 JSON。但是實際上,JSON 和 RESTful API 沒有半毛錢關係,只不過 JSON 恰好是RESTful API 結果的表述格式。也就是說 RESTful API 還可以使用其它的表述格式,例如 xml 或私有的格式。這 ...
現在,當談論起 RESTful Web API 的時候,人們總會想到 JSON。但是實際上,JSON 和 RESTful API 沒有半毛錢關係,只不過 JSON 恰好是RESTful API 結果的表述格式。也就是說 RESTful API 還可以使用其它的表述格式,例如 xml 或私有的格式。這也就意味著,我們需要讓 RESTful API 知道我們想要返回的格式。而這就是HTTP請求和響應的核心內容之一:
Content Negotiation 內容協商
內容協商是這樣一個過程:針對一個響應,當有多種表述格式可用的時候,選取最佳的一個表述。
當我們的RESTful API只面向一個API消費者的時候,也許只使用 JSON 一種格式是沒有什麼問題的。但是如果需要面向各種形式的多個API消費者,那麼很有可能少數API消費者無法很好的解析JSON,它們可能更習慣於xml或者其它格式。
那麼如何解決這個問題呢?
HTTP請求的 Accept Header 就是用來解決這個問題的,API的消費者在發送請求的時候,在Accept Header 裡面填寫好 Media Type(媒體類型),例如 application/json 或者 application/xml等等。
如果請求里填寫的是 application/json,那麼RESTful API返迴響應的表述格式就應該是 json…
而如果請求沒有填寫 Accept Header,那麼 RESTful API 只好使用它的預設格式進行響應了。
如果在 Accept Header 裡面填寫的格式不被 RESTful API 所支持,那麼倒是也可以返回預設的格式,但還是要儘量避免這種情況的出現,其實針對這種情況最好的辦法是返回 406(Not Acceptable) 狀態碼,表示 API消費者請求的媒體類型是不可接受的,無法將其作為響應的格式。
綜上,Accept Header 指的是輸出格式。
在 ASP.NET Core 裡面對應的就是 Output Formatters。
而用於指定輸入格式的 Header是 Content-Type,在 ASP.NET Core 裡面對應的就是 Input formatter。
例如 POST 請求的 body 就需要通過指定 Content-Type 來進行標識,這個 Header 可以看作是自描述性這個約束的一部分(每個消息必須包含足夠的信息來知道如何對它進行處理)。