REST API最佳實踐

我們正在開發一個REST API，並允許所有四種標準動詞。在POST/PUT的情況下，API客戶端將需要修改某些字段的值。就拿僞例如：REST API最佳實踐

class Employee { 
    long Id; 
    long DepartmentId; // should i expose this? 
    string Department; // or should i expose this? 
}

用例這裏是一個客戶端將發佈一個新員工，並填寫所有字段。
有部門在我們的API背後的數據庫中的表
客戶將需要得到有效的部門列表發送
客戶端可以進行API調用來獲取部門這樣的名單：

{ 「部門標識」：「1」，「部」：「技術」 }，
{ 「部門標識」：「2」，「departm ent「：」人力資源「 }

客戶端可以包含上述有效部門之一。我的問題是，如果POST/PUT請求包含部門ID或名稱？該ID似乎比較容易驗證，但對客戶不那麼「友好」。無論哪種情況，我們都可以根據我們的參考表格進行適當的驗證，但我想知道最佳實踐是什麼。

來源

2013-10-15 Adam Levitt

客戶是否會選擇某種形式，如部門的下拉框？我認爲應該有一個「部門」類。 – christiandev

我可以做一個部門班，但這仍然不能真正解決我的問題。我假設API沒有前端，客戶端必須提前請求獲取所有參考數據。 –

API消費者應該向您發送ID *和*完整對象。（新對象（），填充道具，發送東西）和爲你更容易（抓取對象，驗證內容後，按原樣使用它，很少費力）。永遠不要*使用名稱來關聯數據。 – Alex

它應該使用ID。 API消費者必須能夠理解引用。在這種情況下，它需要了解它是指一個特定的部門。爲此，客戶端可能必須首先查詢可用部門列表，但只要您公開此類端點，就不應該擔心。

使用部門名稱會使部門命名一個唯一的鍵，這會更嚴重地改變語義。此外，您可能需要對部門名稱進行索引以有效實現這一點，這是使用該名稱的另一個重大缺點。

來源

2013-10-15 15:31:08 mnemosyn

class Employee { 
    long Id; 
    Department Dept; 
}

或

class Employee { 
     long Id; 
     long DepartmentId; 
    } 

    class Department{ 
     long DepartmentId; 
     string DepartmentName; 
    }

這是類結構吸塵器。至於客戶，他們將需要一個選擇控制來選擇部門 - 你不能指望他們知道該ID或正確的名稱。我已經使用了一個AutoComplete框用於較大的選擇，或者一個dropdown框用於一個小的列表。

要回答什麼發回from客戶端的問題，我會發回ID。

來源

2013-10-15 15:35:48 christiandev

Employee爲什麼包含一個部門？爲什麼員工的主鍵只是'Id'，但部門的主鍵是'DepartmentId'？ – mnemosyn

這個API沒有前端是什麼？客戶需要提前獲得部門清單，這很好，這只是一個問題，讓他們回傳更合理些？ –

@mnemosyn，我沒有拿出命名約定，這是一個假想的例子。員工需要對該部門的引用，要麼具有部門對象，要麼具有PK部門標識。我只是說明員工不應該有部門信息。 – christiandev

通常情況下，更好的做法是使URI表達意義。例如

www.mylocalpaper.com/news/local/politics/2013_town_budget_approved

優於

www.mylocalpaper.com/sections/12/subsection/13/article/45

，因爲第12小節13第45條並不意味着什麼給任何Web服務器代碼之外。顯然要確保每個部門的URL都是唯一的（URL中的U）。

您還應該將完整的URL返回給部門的客戶端，而不僅僅是簡短的名稱，並使用該URL將用戶添加到該部門。因此，返回

{ "add_employee_url": "/departments/tech/employees/", "name": "Technology" }, 
{ "add_employee_url": "/departments/hr/employees/", "name": "Human Resources" }

然後，客戶端只將員工詳細信息發佈到與選擇相匹配的URL。客戶端用戶選擇「技術」並將客戶端文章選擇爲/departments/tech/employees/。

如果部門的URL更改（例如，tech變爲technology），則客戶端將不關心，因爲它正在獲取該操作的完整URL。

來源

2013-10-15 16:42:31

如果Employee對象有許多這樣的字段呢？不僅僅是部門... –

新員工的信息應該在請求的主體中，例如使用JSON或XML或任何格式。將這些數據發佈到/ departments/tech/employees基本上說這是一個新員工資源，請使用此信息（例如姓名，年齡，薪水等）將此新員工添加到此部門。如果服務器決定最終的URL，您可以這樣做，假設它根據數據庫中的自動增量編號爲用戶生成新的ID。然後，服務器應該將它創建的URL返回給客戶端，例如/ departments/tech/employees/13434。 –

如果客戶決定URL，例如說員工資源的URL應該是她已知的員工編號，那麼客戶可以簡單地將數據發送到該URL（例如PUT/department/tech/employees/AB3423）。服務器應該認識到這個員工實際上還沒有在系統中，並且根據這些數據創建一個新的數據庫記錄，但是這個創建應該從客戶端隱藏。如果客戶確定最終的網址，您可以這樣做。 –

REST API最佳實踐

回答

相關問題