联系人管理器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 = "gblock@microsoft.com", Twitter = "gblock" });
contacts.Add(new Contact { ContactId = 2, Name = "Howard Dierking", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "howard@microsoft.com", Twitter = "howard_dierking" });
contacts.Add(new Contact { ContactId = 3, Name = "Yavor Georgiev", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "yavorg@microsoft.com", Twitter = "digthepony" });
contacts.Add(new Contact { ContactId = 4, Name = "Jeff Handley", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "jeff.handley@microsoft.com", Twitter = "jeffhandley" });
contacts.Add(new Contact { ContactId = 5, Name = "Deepesh Mohnani", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "deepm@microsoft.com", Twitter = "deepeshm" });
contacts.Add(new Contact { ContactId = 6, Name = "Brad Olenick", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "brado@microsoft.com", Twitter="brado_23" });
contacts.Add(new Contact { ContactId = 7, Name = "Ron Jacobs", Address = "1 Microsoft Way", City = "Redmond", State = "Washington", Zip = "98112", Email = "rojacobs@microsoft.com", 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的处理，以及状态代码的处理等，现在变成要开注意的几个点。
