公開API端點的JSON模式？

Question

是否有一個標準來揭示API端點模式的位置和方式？

例如，假設下面的API端點可用：

api/companies/ 

api/companies/{id}/employees/ 

應該在哪裏，爲公司和員工資源的模式被曝光？

api/company-schema.json and api/employee-schema.json？

api/schemas/company.json and api/schemas/employee.json？

Answer 1

你可以設置你的架構端點你喜歡的任何方式，但你應該使用推薦的相關方法[1]之一。這個想法是沒有訪問模式的通用規則。相反，資源本身可以識別描述它的模式。

一個典型的例子

請求

GET /api/companies 
Accept: application/json 

響應

HTTP/1.1 200 OK 
Content-Type: application/json; profile="/schema/companies" 

{ ... } 

所以，隨意暴露你的模式，你喜歡的任何方式。如果您需要不必擔心破壞客戶端實施，請隨時更改。只需將您的響應標頭更改爲指向新架構，並且客戶端應該能夠動態處理更改。

Answer 2

爲什麼不把它暴露在被調用的地方？

例如

schema/companies 
schema/companies/10/employees 

更改API來架構