联系人管理器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" (新增、读取、更新、删除) 的简写,这四个动作是数据库基本操作。
![399c00b5ca934c0d39fa5aa2e21dab8ac10716db](https://i-blog.csdnimg.cn/blog_migrate/1acafccb31af6ae0bd3f3a965b900ebb.png)
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的处理,以及状态代码的处理等,现在变成要开注意的几个点。
本文来自云栖社区合作伙伴“doNET跨平台”,了解相关信息可以关注“opendotnet”微信公众号