利用ASP.NET Web API 2构建REST服务实战指南

web

需积分: 3 29 浏览量更新于2024-07-18 收藏 3MB PDF 举报

身份认证购VIP最低享 7 折!

领优惠券(最高得80元）

"ASP.NET Web API 2, 2nd Edition 是一本由 Brian Wortman 和 Jamie Kurtz 撰写的书籍，旨在介绍如何使用ASP.NET Web API 2框架构建世界级的REST服务。本书针对的是版本2.1的Web API框架，该框架已经发展成为构建RESTful服务的强大平台。书中涵盖了技术背景、指导原则以及实用技巧，帮助开发者充分利用ASP.NET Web API 2。书的内容包括服务框架基础、RESTful概念、设计REST API、环境构建、POST操作处理、服务安全、处理关系与复杂性、支持多样化的客户端以及完善服务的各个方面。" 在ASP.NET Web API 2中，开发人员可以构建高度可扩展且易于使用的HTTP服务，这些服务不仅限于浏览器客户端，还可以被各种客户端如移动设备、桌面应用和浏览器插件使用。这本书的章节结构如下： 1. **ASP.NET作为服务框架**：这一章将介绍ASP.NET作为构建服务的基础，探讨其与传统ASP.NET MVC的区别，以及为什么Web API更适合构建REST服务。 2. **什么是RESTful？**：REST（Representational State Transfer）是一种网络应用程序的设计风格和开发方式，本章将深入解释REST的概念，包括资源、URI、HTTP方法等核心概念。 3. **设计示例REST API**：本章将通过实际案例来展示如何设计符合REST原则的API，包括状态码选择、资源表示和版本控制。 4. **构建环境与创建源代码树**：这一部分将指导读者设置开发环境，并建立项目结构，为API开发做好准备。 5. **POST操作上下文**：这一章将详细讲解如何处理HTTP POST请求，包括数据接收、验证和响应生成。 6. **服务安全**：讨论如何保护API不受未经授权的访问，包括身份验证、授权和安全最佳实践。 7. **处理关系、部分更新和其他复杂性**：这部分将涉及如何处理资源之间的关系，实现部分更新，并解决其他在API设计中可能遇到的复杂问题。 8. **支持多样化的客户端**：介绍如何确保API能够适应不同类型的客户端，如JavaScript、iOS、Android等，以及如何利用Content Negotiation实现。 9. **完善画面**：最后一章可能涉及进一步优化API性能、监控、调试和部署策略，以确保服务的稳定性和可靠性。附录包括索引和作者和技术审阅者的信息，方便读者查阅和参考。这本书对于想要深入了解和实践ASP.NET Web API 2的开发者来说是一份宝贵的资源，它不仅提供了理论知识，还包含了大量的实践指南，有助于读者快速上手并创建高效、健壮的REST服务。

资源详情

资源推荐

CHAPTER 2 ■ WHAT IS RESTFUL?

URIs and Resources

As noted briefly in Chapter 1, building a RESTful interface means you end up with an API that is very resource-centric.

As such, you need to intentionally design the interface with resources being at the center. Unlike RPC-style interfaces,

where arbitrary service methods (i.e., the verbs) and their associated request and response messages rule the day,

a REST interface will revolve around the resources (i.e., the nouns). The actions available to those resources are

constrained by the use of HTTP. This is why you must map the available HTTP verbs into the API; you don’t have the

freedom to create other actions or verbs.

This concept is central to a REST design. So let’s examine what the TaskService might look like if it were to move

up to level 1 on the RMM. Table 2-2 shows how each individual resource is addressable by a unique URI.

Table 2-2. Task Service at Level 1 on the RMM

Method URI HTTP verb State changes/contract

CreateTask /api/tasks POST Caller required to know (e.g., WSDL)

GetTask /api/tasks/1234 POST Caller required to know (e.g., WSDL)

GetTaskAssignees /api/tasks/1234 POST Caller required to know (e.g., WSDL)

SearchTasks /api/tasks POST Caller required to know (e.g., WSDL)

UpdateTask /api/tasks/1234 POST Caller required to know (e.g., WSDL)

CompleteTask /api/tasks/1234 POST Caller required to know (e.g., WSDL)

But you still must rely on specific messages for operations. In other words, the caller can’t differentiate between

the two different operations available with the /api/tasks URI unless the caller already has the contract. You’re still

using only the POST HTTP verb, so the request message itself dictates the desired action.

HTTP Verbs

You must look beyond URIs and their resources to the actions needed by the service. These actions will help you

identify the HTTP verbs you need to use. Continuing to follow our example, there’s no such thing as a CreateTask

HTTP verb. In fact, there’s not even a Create verb. If you’re going to leverage the REST architectural style and the

HTTP protocol, you must choose from the verbs available in that protocol, namely these:

GET•

PUT•

POST•

DELETE•

Intuitively, you can quickly eliminate GET and DELETE for the CreateTask action. But what is the difference

in intent between PUT and POST? As shown in Table 2-3, PUT is designed to create or replace a resource with

a known identifier, and hence a known unique URI. You use a POST when the system is generating the new

resource’s identifier.

CHAPTER 2 ■ WHAT IS RESTFUL?

Technically speaking, the REST architectural style is agnostic about any specific protocol. That includes the HTTP

protocol. In other words, all you need is a protocol that provides a language and mechanism for describing both states

(i.e., representations) and state changes. However, since this book is about building a REST service with the ASP.NET

Web API, you’ll focus on REST with HTTP. Fortunately, the HTTP protocol itself covers most of what you need.

Let’s walk through some important concepts with this mapping. First, the exact meaning of each of the four verbs

is dependent on the URI. So even though you have only four verbs, you actually have eight different actions available

to you. The difference lies in whether the URI defines a collection or a unique element.

Second, when creating new instances of the resource (e.g., a new task), PUT is used with a unique URI in the

scenario where the caller generates the new resource’s identifier before submitting the request to the server. In

Table 2-3, the PUT action is used with a unique element URI to create a new task with the specific identifier, 1234.

If instead the system is to generate the identifier, the caller uses the POST action and a collection URI. This also ties

into the concept of idempotency.

The GET, PUT, and DELETE methods are said to be idempotent; that is, calling them over and over will produce

the same result without any additional side effects. For example, the caller should be able to call the DELETE action

on a specific resource without receiving any errors and without harming the system. If the resource has already been

deleted, the caller should not receive an error. The same applies to the PUT action. For a given unique resource

(identified by an element URI), submitting a PUT request should update the resource if it already exists. Or, if it

doesn’t exist, the system should create the resource as submitted. In other words, calling PUT over and over produces

the same result without any additional side effects (i.e., the new task will exist in the system per the representation

provided by the caller, whether the system had to create a new one or update an existing one).

The GET action is also said to be safe. Safe means that nothing in the system is changed at all, which is appropriate

for HTTP calls that are meant to query the system for either a collection of resources or for a specific resource.

It is important that the idempotency of the service’s GET, PUT, and DELETE operations remain consistent with

the HTTP protocol standards. Thus, every effort should be made to ensure those three actions can be called over and

over without error.

Unlike the other three actions, POST is not considered to be idempotent. This is because POST is used to create

a new instance of the identified resource type for every invocation of the method. Where calling PUT over and

over will never result in more than one resource being created or updated, calling POST will result in new resource

instances—one for each call. This is appropriate for cases where the system must generate the new resource’s

identifier and return it in the response.

As you model your task-management service, you will need to map each resource with a set of HTTP actions,

defining which ones are allowed and which ones aren’t supported.

Now let’s take a new look at the task service. This time around, you’ll use the available HTTP verbs, which will put

you at level 2 on the RMM. (See Table 2-4.)

Table 2-3. Using HTTP Verbs with the Task Resource

HTTP verb (Collection URI)

http://myserver.com/tasks

(Element URI)

http://myserver.com/tasks/1234

GET List of tasks, including URIs to individual tasks Get a specific task, identified by the URI

PUT Replace the entire collection of tasks Replace or create the single task identified

by the URI

POST Create a new single task, where its identifier is

generated by the system

Create a new subordinate under the task

identified by the URI

DELETE Delete the entire collection of tasks Delete the tasks identified by the URI

CHAPTER 2 ■ WHAT IS RESTFUL?

At this point, the service is utilizing unique URIs for individual resources, and you’ve switched to using HTTP

verbs instead of custom request message types. That is, each of the PUT and POST actions mentioned previously will

simply take a representation of a task resource (e.g., XML or JSON). However, the client must still have prior knowledge

of the API in order to traverse the domain and to perform any operations more complex than creating, updating,

or completing a task. In the true nature of the Web, you should instead fully guide the client, providing all available

resources and actions via links and forms. This is what is meant by “hypermedia as the engine of application state.”

HATEOAS

As you look at Tables 2-3 and 2-4, you can see that certain GET operations will return collections of resources. One of

the guiding principles of REST with HTTP is that callers make transitions through application state only by navigating

hypermedia provided by the server. In other words, given a root or starting URI, the caller should be able to navigate

the collection of resources without prior knowledge of the possible navigation paths. Thus, whenever a resource is

returned from the service, whether in a collection or by itself, the returned data should include the URI required to

turn around and perform another GET to retrieve just that resource.

Here’s an example of an XML response message that illustrates how each element in the collection should

contain a URI to the resource:

<?xml version="1.0" encoding="utf-8"?>

<Tasks>

</Task>

</Task>

</Tasks>

Note ■ The actual href will include the URI’s scheme, host, and where required, port (e.g., href=”

http://www.foo.com/api/tasks/1234

). We are omitting these details to focus on concepts and reduce clutter.

It is typically appropriate to return only a few attributes or pieces of data when responding with a collection, such

as in the preceding example. Now the caller can use the URI to query a specific resource to retrieve all attributes of

that resource. For example, the Tasks collection response (as just shown) might contain only the Task’s Id and a URI

to fetch the Task resource. But when calling GET to get a specific Task, the response might include TaskCategory,

DateCreated, TaskStatus, TaskOwner, and so on.

Table 2-4. Task Service at Level 2 in the RMM

Method URI HTTP verb State changes/contract

CreateTask /api/tasks POST Caller required to know (e.g., WSDL)

GetTask /api/tasks/1234 GET Caller required to know (e.g., WSDL)

GetTaskAssignees /api/tasks/1234/users GET Caller required to know (e.g., WSDL)

SearchTasks /api/tasks GET Caller required to know (e.g., WSDL)

UpdateTask /api/tasks/1234 PUT Caller required to know (e.g., WSDL)

CompleteTask /api/tasks/1234 DELETE Caller required to know (e.g., WSDL)

CHAPTER 2 ■ WHAT IS RESTFUL?

Taking this approach can be a little trickier when using strongly typed model objects in .NET (or any other OO

language). This is because you need to define at least two different variants of the Task type. The typical pattern is

to have a TaskInfo class and a Task class, where the TaskInfo class exists only to provide basic information about a

Task. The collection might look like this:

<?xml version="1.0" encoding="utf-8"?>

<Tasks>

</TaskInfo>

</TaskInfo>

</Tasks>

And the single resource might look like this:

<?xml version="1.0" encoding="utf-8"?>

</Task>

Utilizing two different types like this is not a requirement for REST or any other service API-style. You may find

that you don’t need to separate collection type definitions from other definitions. Or you may find that you need

many more than two. It all depends on the usage scenarios and how many different attributes exist on the resource.

For example, if the Task resource included only five or six attributes, you probably wouldn’t create a separate type for

the collection objects. But if the Task object were to include 100 or more attributes (as is typical in something like a

financial application), it might be a good idea to create more than one variation of the Task type.

Within the realm of HATEOAS, you also want to guide the user as to the actions available on a resource. You just

saw how you can use a <link> element to provide a reference for fetching task details. You can expand this concept to

include all available resources and actions. Remember, when browsing a web site, a user needs to have prior knowledge

only of the root address to traverse the entire site. You want to provide a similar experience to callers of the API.

Here’s what a full HATEOAS-compliant XML response might look like for the TaskInfo type:

<?xml version="1.0" encoding="utf-8"?>

<Tasks>

</TaskInfo>

</TaskInfo>

</Tasks>

CHAPTER 2 ■ WHAT IS RESTFUL?

Note that the links available to each task are a little different. This is because you don’t need to complete an

already completed task. Instead, you need to offer a link to reopen it. Also, you don’t want to allow updates on a

completed task, so that link is not present in the completed task.

LINK phILOSOphY

We want to offer a disclaimer and a word of warning for the topic of links in REST messages. You find that, over

the past several years, the debate over how the HTTP verbs are supposed to be used can be quite heated at

times. This debate also extends into how to best design URIs to be most RESTful—without degenerating into a

SOAP-style API.

For example, in the Task XML you just looked at, it specifies the “reopen” link as a PUT to the /api/tasks/0987

URI. It also specifies the “complete” link as a DELETE to the /api/tasks/1234 URI. These approaches are neither

specified by the REST architectural style, nor are they even agreed upon by the folks who practice REST. And for

whatever reason, people on various sides of the debate tend to get worked up about their way of doing things.

Instead of using a PUT against the resource URI for the “reopen” action, you could instead use a PUT against

a URI like /api/tasks/0987/reopen. We tend to lean away from this approach, as it pushes you closer to

specifying actions instead of resources (for the URI). However, we also think it’s a bit unrealistic to assume you

can accommodate all available actions on something like a

Task object with only four HTTP verbs. Indeed, there

are a few more verbs you can use, including PATCH, HEAD, and OPTIONS. But even so, the set of available verbs

is limited, and the REST architectural style dictates that you don’t add to those verbs. So at some point, you need

to make a judgment call as to how to implement various actions on the Task object. The important thing is to

conform as closely to HTTP standards as possible.

The use of the DELETE verb is also hotly debated. Most enterprise applications don’t allow the caller to really

delete a resource. More often, a resource is merely closed, inactivated, hidden, and so on. As such, it might seem

reasonable to not waste one of your precious few verbs on an action that you never even allow, when instead you

could use it for the “close” action.

As with most endeavors in the world of software, the devil’s in the details. And you can usually find 101 ways to

implement those details if you look hard enough. Our advice here is to simply do the best you can, don’t be afraid

to be wrong, and don’t get stuck in an infinite loop of forever debating the very best approach to follow. Think,

commit, and go.

You can now complete the table of task resources and operations using the three concepts you’ve learned from

the RMM:

URIs and resources•

HTTP verbs•

HATEOAS•

Table 2-5 illustrates the task service under a more ideal RESTful design. That is, it shows the things you can do

to make the service self-describing (i.e., related information and available operations are given to the caller via links

contained in the service’s responses). Again, following the RMM isn’t sufficient in itself to being able to claim your

service is a REST service. But you also can’t claim compliance with REST without following it, either.

www.allitebooks.com

剩余265页未读，继续阅读

mingscsdn

粉丝: 2
资源: 21

利用ASP.NET Web API 2构建REST服务实战指南

ASP.NET Web API 2, 2nd Edition.pdf

ASP.NET Web API 2 Recipes（英文pdf）

ASP.NET Web API and Angular 2 pdf 0分

asp.net web api 2框架揭秘电子书

asp.net webapi快速开发框架

使用 ASP.NET Web API 構建超媒體 Web API

asp.net web api

asp.net webapi 路径映射

asp.net webapi增删查改sql

ASP.NET webapi 登录登出

.net webapi petshop

ASP.NET Core和ASP.net webapicore区别

ASP.NET Web API 2 ，返回字符串。以及JS如何调用这个Web API

asp.net webservices api接口

推荐.NET webapi学习

asp.net core webapi有什么用

ASP.NET Web API 2 ，带参数的API。以及JS如何调用这个Web API

asp.net core web api框架

asp.net web api参数缺省

asp.net core web api

最新资源