Contact Manager Web API 示例[1]CRUD 操作

聯系人管理器web API是一個Asp.net web api示例程序，演示了通過ASP.NET Web API 公開聯系信息,並允許您添加和刪除聯系人，示例地址http://code.msdn.microsoft.com/Contact-Manager-Web-API-0e8e373d . 下面的文章以這個示例講解ASP.NET Web API的各方面知識：

1、CRUD操作: CURD 是 "Create, Read, Update, Delete" (新增、讀取、更新、刪除) 的簡寫，這四個動作是數據庫基本操作。

Web API CRUD 方法說明
Action說明	HTTP方法	URI關連
取得所有聯系人清單	GET	/api/contacts
透過 id 取得聯系人數據	GET	/api/contacts/id
新增一位聯系人	POST	/api/contacts
更新聯系人數據	PUT	/api/contacts/id
刪除聯系人數據	DELETE	/api/contacts/id

由上表中，我們可以很清楚看到，有兩種資源類型( resource types)：

URI 資源類型
URI	說明
/api/contacts	列出所有聯系人
/api/contacts/id	一位聯系人

HTTP 方法

HTTP 主要方法 (GET, PUT, POST, DELETE) 能對應到 CURD 操作：

· GET 接收及顯示。GET 在服務器應該沒有副作用。

· PUT 更新。PUT 也能拿來"新增"使用，如果服務器允許 Client 去指定新的 URI。那范例的聯系人管理將不允許使用 PUT 來新增。

· POST 新增。服務器會給 URI 分配新對象，然后返回此 URI 作為響應消息的一部分。

· DELETE 刪除。

 

新增資源

在 ASP.NET Web API，你能在 Model 使用強型別 CLR 對象，他們將會自動序列化為 XML 或 JSON 給 Client。在Model 目錄的 Contact 類：

public class Contact
    {
        public int ContactId { get; set; }

        public string Name { get; set; }

        public string Address { get; set; }
        public string City { get; set; }
        public string State { get; set; }
        public string Zip { get; set; }
        public string Email { get; set; }
        public string Twitter { get; set; }

        public string Self
        {
            get { return string.Format(CultureInfo.CurrentCulture, "contact/{0}", this.ContactId); }
            set { }
        }
    }

使用倉儲模式( Repository Pattern)

我們的 HTTP Service 需要儲存聯系人列表，此范例，聯系人列表會儲存在內存( List(Of T ) )。使用 Repository Pattern 會讓此對象從我們的 Service 實作中切割出來。在 Model 目錄，新增一個 Interface 接口，名稱 IContactRepository.cs

public interface IContactRepository
   {
       void Update(Contact updatedContact);

       Contact Get(int id);

       List<Contact> GetAll();

       void Post(Contact contact);

       void Delete(int id);
   }

以上定義出我們需要的 CRUD 相關功能接口，然后一樣在 Model 目錄下新增一個新的類文件，類文件 "ContactRepository.cs"，此類將實作 IContactRepository 接口。以下為相關實現：

    public class ContactRepository : IContactRepository
    {
        private int nextContactID;

        private IList<Contact> contacts;

        public ContactRepository()
        {
            contacts = new List<Contact>();
            contacts.Add(new Contact { ContactId = 1, Name = "Glenn Block", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "[e-mail]", Twitter = "gblock" });
            contacts.Add(new Contact { ContactId = 2, Name = "Howard Dierking", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "[e-mail]", Twitter = "howard_dierking" });
            contacts.Add(new Contact { ContactId = 3, Name = "Yavor Georgiev", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "[e-mail]", Twitter = "digthepony" });
            contacts.Add(new Contact { ContactId = 4, Name = "Jeff Handley", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "[e-mail]", Twitter = "jeffhandley" });
            contacts.Add(new Contact { ContactId = 5, Name = "Deepesh Mohnani", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "[e-mail]", Twitter = "deepeshm" });
            contacts.Add(new Contact { ContactId = 6, Name = "Brad Olenick", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "[e-mail]", Twitter="brado_23" });
            contacts.Add(new Contact { ContactId = 7, Name = "Ron Jacobs", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "[e-mail]", Twitter = "ronljacobs" });
            nextContactID = contacts.Count + 1;
        }

        public void Update(Contact updatedContact)
        {
            var contact = this.Get(updatedContact.ContactId);
            contact.Name = updatedContact.Name;
            contact.Address = updatedContact.Address;
            contact.City = updatedContact.City;
            contact.State = updatedContact.State;
            contact.Zip = updatedContact.Zip;
            contact.Email = updatedContact.Email;
            contact.Twitter = updatedContact.Twitter;
        }

        public Contact Get(int id)
        {
            return contacts.SingleOrDefault(c => c.ContactId == id);
        }

        public List<Contact> GetAll()
        {
            return contacts.ToList();
        }

        public void Post(Contact contact)
        {
            contact.ContactId = nextContactID++;
            contacts.Add(contact);
        }

        public void Delete(int id)
        {
            var contact = this.Get(id);
            contacts.Remove(contact);
        }
    }

實現沒有什么難處，要處理都是 List(Of Contact) 所提供的 .Add(), .Remove(), .Find() 以進行相關新增、刪除、查詢動作。另外，還利用 LINQ 的 .AsQueryable() 來將 List 型別轉換，才有辦法以 IQueryable() 來回傳。以上利用 List 來仿真數據庫，或者說，把 List 想象成內存里的數據庫。

Web API Controller（ContactsController）

ContactsController是 HTTP Service 的程序代碼，注意命名開始要對應到 HTTP Method，主要就是約定勝於配置理念。“約定”即規則。規則是預先定義的，工程師只需要按着規則來做事，就不需要額外的“配置”。當然也可以不對應，通過HttpMothod打標簽也可以的。

取得資源

取得資源是 Read 與 GET 的對應關系。在聯系人管理中提供了二個 Action，一個是讀取所有聯系人，一個是通過 id 來取得聯系人。這兩個 Action 都定義在 HTTP GET 方法，記得方法必須以 "Get..." 開頭。

· GET /api/contacts

· GET /api/contacts/id

新增資源

新增資源是 Create 與 POST 的對應關系。要新增一位聯系人，Client 送出一個 HTTP POST 請求，請求信息包含新聯系人的相關內容。記得方法必須以 "Post..." 開頭。

        public HttpResponseMessage<Contact> Post(Contact contact)
        {
            this.repository.Post(contact);
            var response = new HttpResponseMessage<Contact>(contact) { StatusCode = HttpStatusCode.Created };

           string uri = Url.Route("default", new { id = contact.ContactId });

            response.Headers.Location = new Uri(Request.RequestUri, uri);

             return response;
        }

默認從請求主體(request body)來而的參數解序列化后是復合(complex)類型。因此，我們預期 Client 傳送給我們的是一個經序列化表現的聯系人對象，使用 XML 或 JSON 來序列化。以上的實現考慮到兩件事：

· Response code
默認，Web API Framework 設定回傳狀態代碼(status code)為 200 (OK)。但按照 HTTP/1.1 協議，當一個 POST 請求會導致資源的建立，服務器應該響應的狀態代碼為 201 (Created)。

· Location當服務器新增一個資源，它應該在響應的 Location header 中包含新資源的 URI。

注意返回類型是 HttpResponseMessage(Of Contact)，HttpResponseMessage(Of T) 型別是一個用強類型表示的 HTTP 響應消息。泛型參數 T 會取得 CLR 型別然后序列化到信息主體。

更新資源

更新資源是 Update 與 PUT 的對應關系。更新聯系人作法相當直覺，記得方法必須以 "Put..." 開頭。

public Contact Put(int id, Contact contact)
{
           contact.ContactId = id;
           this.repository.Update(contact);
           return contact;
}

方法中有二個參教，聯系人 id 與 更新的聯系人數據。id 參數會從 URI 路徑取得，聯系人參數是從請求主體解串行化而來。默認，ASP.NET Web API Framework 會從請求主體 (request body)里的 route 與 復合(complex) 型別來取得簡易的參數類型。

刪除資源

刪除資源是 Delete 與 DELETE 的對應關系。

public HttpResponseMessage Delete(int id)
{
            var deleted = this.repository.Get(id);
            this.repository.Delete(id);
            return new HttpResponseMessage(HttpStatusCode.NoContent);

}

依據 HTTP 規范，DELETE 方法必須是 idmpotent(冪等)，意味着幾個相同 URI 的刪除請求必須和一個刪除請求有相同效果。因此，如果聯系人已經被刪除，方法應該不能回傳錯誤碼。
如果 DELETE 請求成功，你能回傳狀態 200 (OK) 描述該實體主體(即要刪除的主體)的狀態，或如果刪除持續未處理回傳狀態 202 (Accepted) ，或沒有實體主體回傳狀態 204 (No Content)。我們范例會返回狀態 204 (No Content)。

CRUD 操作總結

在使用 ASP.NET Web API Framework 時，你能發現與 HTTP/1.1 規范有很大關連性，以前較很少關心與了解的內容，例如，PUT、DELETE、POST的處理，以及狀態代碼的處理等，現在變成要開注意的幾個點。