Tải bản đầy đủ
Objective 4.1: Design a Web API

Objective 4.1: Design a Web API

Tải bản đầy đủ

Web API builds upon the standard HTTP verbs, routing to define your URLs and content negotiation to exchange data with clients.
The focus of this objective is on making sure you understand the conceptual idea behind
the Web API, which is important for the exam. For example, you can expect questions on
choosing the correct HTTP methods and creating a URL scheme for your Web API.

This objective covers how to:
■■

Choose appropriate HTTP method (get, put, post, delete) to meet requirements

■■

Define HTTP resources with HTTP actions

■■

Plan appropriate URI space and map URI space using routing

■■

■■

Choose appropriate format (Web API formats) for responses to meet
requirements
Plan when to make HTTP actions asynchronous

Choosing appropriate HTTP methods
To understand Web API, you need to understand how HTTP works. Representational State
Transfer (REST) services are built upon HTTP. Instead of calling a specific method, you access
a URL in combination with an HTTP method. Because Web API is a RESTful solution, it’s very
important (both in the real world and for the exam) to understand the various HTTP methods
and what they do. When accessing a Web API, you do this by requesting a URL. The HTTP
method that you use on that URL determines what will happen.
Because you’re working with HTTP, it’s also important to know what to return to the client.
Status codes such as 200 (OK), 201 (Created), 400 (Bad Request), and 404 (Not Found) are often used. They inform the caller of your service of what happened. Next to using the correct
HTTP method, it’s equally important to use the correct status code.
There are seven items of primary concern and they are shown in Table 4-1.
TABLE 4-1  HTTP Verbs

288

Verb

CRUD action

Behavior

Delete

Delete

Specifies that a given URI be deleted.

Get

Read

Retrieves one or more entities or some other data that is identified
by the URI of the request.

Put

Update

Replaces an entity that is identified by the URI. By standards, this
verb requires all fields on the entity be specified, regardless of how
many change.

Post

Create

Inserts a new entity to the URI.

Head

N/A

Retrieves just the message headers identified by the URI.

CHAPTER 4

Creating and consuming Web API-based services

Verb

CRUD action

Behavior

Patch

Update

Transmits a partial change to the entity identified by the URI where
only identifiers and modified fields are specified.

Options

N/A

Represents requests for information about the communication options available on the target resource.

Each value has its own purpose and need, but for the most part, you’ll want to focus on
how each is used with respect to common data operations frequently referred to as Create,
Read, Update, and Delete (CRUD).

HttpGet
Just about all query or retrieval operations are implemented as HttpGet actions. Although not
always the case, the number of methods that are implemented as HttpGet actions are usually
the highest. For any given object that’s represented by a model, there is typically at least the
need to retrieve all the items in the dataset and then one that allows for individual retrieval
by the key. Table 4-2 shows a basic REST scheme for retrieval centered on a given model (in
practice, you have several different models represented and as such, you likely have several
different HttpGet methods).
TABLE 4-2  HttpGet retrieval

Action

URI

Get a list of all Foos

/api/Foos

Get an instance of Foo by key field

/api/Foos/keyvalue

Get an instance of Foo by an attribute

/api/Foos?attributename=attributevalue

Although not a strict requirement, generally you need to differentiate between a request
that is malformed or points to something that doesn’t exist, and one that simply doesn’t contain matching values. If you search for a hard-coded set of customers for one who has the last
name of Doe, and none is found, it is a different scenario from one in which a request is made
for race car drivers.
Checking for a valid result inside the method implementation and throwing an HttpResponseException with an HttpStatusCode of NotFound accomplishes this in a direct manner.
Although both would result in a 404, the unhandled 404 also comes with an error message
stating that it was unhandled to provide an additional explanation.

HttpDelete
Arguably the easiest of the set to identify, HttpDelete requests are straightforward to both
identify and implement. The most common way to accomplish the deletion of a record is to
specify the dataset key and use it to identify and delete the record. For the sake of clarity, it’s
advisable to name any such operations with a prefix of Delete.



Objective 4.1: Design a Web API

CHAPTER 4

289

As is the case with retrieval operations, it’s desirable to provide some sort of feedback to
the end user indicating that the operation was successful. There are three possible outcomes,
assuming that the request is correctly formed and processed:
■■

■■

■■

The first is a successfully processed request that has an HttpStatusCode of OK (200).
A valid response is returned to the client, and information from the request can be
included.
The next outcome is an HttpStatusCode of Accepted (202), which indicates that the
request was processed and accepted, but is still pending.
The last outcome is an HttpStatusCode of No Response (204). It’s important to note
that the method return type can directly affect this value. When the type has a void
return type, a value of 204 is automatically transmitted back to the client.

HttpPost
When you want to insert new data, the HttpPost verb is typically used. In accord with the
method’s behavior, Post operations should be named with a prefix of Post. If any exam question or requirement specifies that a new record be created, it will probably necessitate an
HttpPost operation.
A method that maps to an HttpPost request can have various return types (including void).
It almost always requires an input parameter corresponding to the type that’s being inserted
or created.
If you’re attempting to insert a new record, it makes sense to get some feedback that the
operation was successful. (If you think back to ADO.NET, for instance, when performing an
INSERT operation, the ExecuteNonQuery method has a RecordsAffected property indicating how many records were just inserted.) Although this makes sense, and there’s nothing
stopping you from doing it, the HTTP 1.1 protocol stipulates that when a resource is created,
the server responds with an HttpStatusCode of Created (201). If you don’t specify otherwise,
though, when the operation is processed, the framework returns an HttpStatusCode of OK
(200), so you have to put effort into returning a 201.
Additionally, when a new resource is created, it’s advisable that the location of the new
resource be included in the response. This enables a user of your API to immediately get the
feedback where it can find any details on the entity that was just added. For both of these
reasons, the following method would compile and run:
// Don't use this
public int PostAccount(Account account)
{
return 0;
}

Even though it would technically work, it’s equally a bad idea for precisely the two reasons
stated previously. A better implementation and one that would use the System.Net.Http.
HttpResponseMessage as the return type and would provide information about the operation
is the HttpResponseMessage:

290

CHAPTER 4

Creating and consuming Web API-based services

[HttpPost]
public HttpResponseMessage PostAccount(Account account)
{
HttpResponseMessage response =
Request.CreateResponse(HttpStatusCode.Created, account);
string newUri = Url.Link("NamedApi", new { accountId = account.AccountId });
response.Headers.Location = new Uri(newUri);
return response;
}

This implementation returns a 201 status code and points to the location of the newly
created item.

HttpPut
The HttpPut is used for operations that correspond to upserts, inserting for new records and
updating for existing records. An interesting side effect of supporting upserts is that the
method should be idempotent (that is, if you call the method once or 100 times with the
same data, there should be no meaningful difference in the side effects of calling it one or
100 times).
Any methods that execute update operations should use the Put prefix. Following along
with the examples, to have an update for an Account, you’d need to specify a key to look up
the record and then a container to hold the new values. Implementation is simple, and the
only noteworthy component is prefixing the method name with Put:
[HttpPut]
public HttpResponseMessage PutAccount(int id, Account account)
{
// perform insert and/or edit here.
}

NOTE  SOURCE VALUES

Just as with the ASP.NET Model-View-Controller (MVC), Web API uses model binding to
create the arguments necessary for your method. For example, the ID parameter to the
PutAccount method can be extracted from the corresponding value if that’s specified in
the RouteTemplate. The account parameter is extracted by deserializing the request body.
Being able to send data both in the URL and the request body makes sense if you think
about it with respect to how it’s being processed. A typical request often involves more
than one value, and in many cases, it will involve several values. A key, on the other hand, is
exclusive and must by definition be a scalar value. As such, the key lends itself to intuitive
representation via the URI, but trying to specify 20 values would be quite convoluted. Using simple parameter types extracted from the Route while extracting complex types from
the Request body not only makes sense but also allows for items being addressable by URI
without making them impossible to understand or build.



Objective 4.1: Design a Web API

CHAPTER 4

291

NOTE  PERFORMING UPDATES WITH PUT, PATCH, AND/OR POST

This is a topic that is both easily confused and that has caused some heated debate. Which
one should be used for performing an update? As with most questions that cause a heated
debate, there is not a solid obvious answer. Even REST purists often argue about what you
should use! It is the opinion of this author that the best answer is this: It depends.
Before you continue, reread the preceding Put description, specifically about it being
idempotent. This is a very critical differentiator. The difference between Post and Put is
almost akin to saying Collection.Add(foo) versus Collection[7] = foo. If a collection had no
item in which index == 7 (and your collection enabled you to insert like this), both lines of
code would have the same result. However, if you executed both lines of code 100 times,
the results would be very different!
Patch differs from Put and Post in that it need not specify all data for a resource; only the
data that must change. For instance, if you have an operation that changes the last name
of somebody due to a recent marriage, it might make sense to use Patch, as you care only
about the one field (and an identifier), but all the other fields are inconsequential.
Now there is one final question that none of this answers: What is the correct answer
for the exam? Fortunately, Web API is certainly flexible enough so you could implement
RESTful services as strictly or loosely as you see fit. So the answer here is twofold. First, you
ultimately get to choose what the best method is when performing an update. However,
if you absolutely must generalize everything to a simple equivalent of CRUD, it would be
wise to assign Put as being the analog to updates. However, be aware that the real answer
is: It depends. As such, you might occasionally see mentions in this book assigning an update behavior to Put, but this short discussion is the only reason why.

Defining HTTP resources with HTTP actions
Now that you understand the HTTP methods involved in creating a Web API service, it’s time
to start looking at how to use them in Web API.
First, let’s contrast a Web API service with a WCF service. If you think back to a traditional
WCF Service, you need to follow the ABC pattern: address, binding, and contract. The address
specifies the location of your service, the binding configures how you can call the service, and
the contract defines your actual service.
Items you create to transfer the data need to be serialized, and the most common mechanism is to decorate the type with the DataContract attribute. Each property that you want
exposed should be decorated with the DataMember attribute.
You have complete freedom in how you create your service. This gives you a lot of flexibility and power, but it also introduces complexity. Another problem with the complexity of
WCF is that it often creates a strong coupling between the client and the server. In today’s
world, more and more devices need to access your services. Not all those devices are running

292

CHAPTER 4

Creating and consuming Web API-based services

on the .NET platform. The only ubiquitous feature is HTTP. All modern devices are capable of
executing HTPP requests and retrieving the results.
This is why Web API is built upon HTTP. When building a service with a Web API, you build
an application that uses controllers and action methods that map to specific URLs and HTTP
actions.
After you choose to create the application, you’ll be prompted to specify the template you
want to use when the project is created. Unsurprisingly, you should choose the Web API option shown in Figure 4-1.

FIGURE 4-1  Web API template dialog box



Objective 4.1: Design a Web API

CHAPTER 4

293

NOTE  VISUAL STUDIO 2013

Creating a Web API project in Visual Studio 2013 is a bit different. In Visual Studio 2013,
you no longer specify a Model-View-Controller (MVC) 4 project at the first stage, but need
only specify an ASP.NET Web Application. This is because Microsoft is moving to One ASP.
NET. Instead of having all the different flavors (Web Forms, Dynamic Data, MVC, Web API),
they are all merged together in one single ASP.NET. This means you can easily mix Web
Forms (maybe for a back-end part of your site) with MVC (for the front end) and Web API
(to expose some services). Because Visual Studio 2013 is not yet final at the time of the
writing of this book, the exact details might change by the time it is released, but the idea
of One ASP.NET is definitely going to stay. As long as Visual Studio 2013 is not officially
released, you shouldn’t expect any questions on the exam, but when it’s released, you can
expect the exam to adopt the changes.

With the application in place, you can define the resources and corresponding actions.

Creating the model
When designing your Web API, you probably have some data that you want to expose. This is
why you don’t technically need to create the model first, but it is the logical way to proceed.
The model you define is a physical representation of the data you want to transfer. Unlike its
WCF counterpart, there’s nothing special about creating a model; you define it just like any
other .NET Class.
Once defined, the ASP.NET Web API transparently handles sending your model over HTTP.
It does so by serializing your model’s members to the target format. JavaScript Object Notation (JSON) and XML are two of the best-known formats. After the model’s information is
serialized, the framework will take the serialized data and insert it into the Body element of
the HTTP response message. JSON and XML are both ubiquitous in the development world,
and both can be read on almost every platform and every technology. As long as a client can
read the chosen format, it can deserialize the object and enable you to work with it however
you desire.
When the project is created for you by Visual Studio, it creates several project folders for
you that allow convenient and intuitive locations to store the components of the service. For
more complex applications, you probably store your model in a separate assembly. But in this
case, create each item that serves as a model in the Models folder in the Solution Explorer. To
illustrate how this works (and how simple it is), define two items like this:

294

CHAPTER 4

Creating and consuming Web API-based services

Account.cs in the Models folder
public class Account
{
public int AccountId { get; set; }
public string AccountAlias { get; set; }
public DateTime CreatedDate { get; set; }
}
Customer.cs in the Models folder
public class Customer
{
public int CustomerId { get; set; }
public int AccountId { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
}

The only thing noteworthy about either of these two class definitions is that there is nothing noteworthy about them! They have no special constructor that needs to be implemented.
There is no requirement to inherit from a base class or to implement an interface. A special
attribute decoration is not needed. To that end, each of these classes looks like any other .NET
class. The only requirement worth mentioning is that the model definition must provide for a
nonprivate default constructor.

Creating the controller
Controller classes are the most important part of your Web API. They define the actual service
that you expose to users. The primary purpose of the controller is to handle HTTP requests.
The controller implementation you create needs to inherit from the ApiController class. The
members that manipulate the model types are known as action methods, action handlers, or
simply actions. No extra attributes are needed on a method to facilitate it becoming an action; it simply needs to be a public method defined as part of the controller instance.
To expose the Account and Customer class that you just created, create a class derived
from the System.Web.Http.ApiController base class in the Controllers folder. Define an array
of Account items and prepopulate the array with data. In a real-world scenario, instead of
using hard-coded data, the data would be retrieved from a Web Service, XML file, SQL Server
database, or other store. In fact, you can very easily hook this up to a database by using the
Entity Framework or any other data access technology you choose.
In this example, you’ll build the following retrieval methods:



■■

Return all available Accounts

■■

Return a specific Account based on the AccountId

■■

Return all Customers on a specific AccountId

■■

Search all Customers on a specific AccountId by Last Name

Objective 4.1: Design a Web API

CHAPTER 4

295

The first step is to create the controller objects in the Controllers folder. Following the REST
pattern, you expose a service for each model type that you have. In this case, you add a controller for both Accounts and Customers. The following uses stub in the action handlers:
AccountController.cs
public class AccountController : ApiController
{
public IEnumerable GetAccounts()
{
throw new NotImplementedException("You still need to write this logic");
}
public Account GetAccount(int accountId)
{
throw new NotImplementedException("You still need to write this logic");
}
}
CustomerController.cs
public class CustomerController : ApiController
{
public IEnumerable GetCustomers(int accountId)
{
throw new NotImplementedException("You still need to write this logic");
}
public IEnumerable SearchCustomers(int accountId, string lastName)
{
throw new NotImplementedException("You still need to write this logic");
}
}

Next, prepopulate an array of Accounts and an array of Customers so you have data to
work with. Place them in a new class file named DataRepository in the Web API project’s root
directory:
DataRepository.cs in MyWebApi’s root directory
public static class DataRepository
{
public static Account[] Accounts = new Account[]
{
new Account{ AccountId = 1, AccountAlias = "Disney"},
new Account{ AccountId = 2, AccountAlias = "Marvel"},
new Account{ AccountId = 3, AccountAlias = "McDonald's"},
new Account{ AccountId = 4, AccountAlias = "Flintstones"}
};
public static Customer[] Customers = new Customer[]
{
new Customer{ AccountId = 1, CustomerId = 1,
FirstName = "Mickey", LastName = "Mouse"},
new Customer{ AccountId = 1, CustomerId = 2,
FirstName = "Minnie", LastName = "Mouse"},
new Customer{ AccountId = 1, CustomerId = 3,
FirstName = "Donald", LastName = "Duck"},
new Customer{ AccountId = 2, CustomerId = 4,

296

CHAPTER 4

Creating and consuming Web API-based services

FirstName
new Customer{
FirstName
new Customer{
FirstName
new Customer{
FirstName
new Customer{
FirstName
new Customer{
FirstName
new Customer{
FirstName
new Customer{
FirstName
new Customer{
FirstName

= "Captain", LastName = "America"},
AccountId = 2, CustomerId = 5,
= "Spider", LastName = "Man"},
AccountId = 2, CustomerId = 6,
= "Wolverine", LastName = "N/A"},
AccountId = 3, CustomerId = 7,
= "Ronald", LastName = "McDonald"},
AccountId = 3, CustomerId = 8,
= "Ham", LastName = "Burgler"},
AccountId = 4, CustomerId = 9,
= "Fred", LastName = "Flintstone"},
AccountId = 4, CustomerId = 10,
= "Wilma", LastName = "Flintstone"},
AccountId = 4, CustomerId = 11,
= "Betty", LastName = "Rubble"},
AccountId = 4, CustomerId = 12,
= "Barney", LastName = "Rubble"}

};
}

NOTE  MVC AND WEB API

For organizational purposes, it is helpful to store controllers in the predefined Controllers
folder, but it’s not an absolute requirement. Also, when you go to create a new controller,
you can add a controller in the Solution Explorer’s context menus for the Controllers folder.
However, this adds an MVC controller, not a Web API controller (this will be fixed in Visual
Studio 2013). It is actually easier to just add a new Class because you have to remove the
majority of what is in the initial controller template. Finally, be sure to include the System.
Web.Http namespace so the ApiController base class can be resolved.

The only remaining task is to implement the functionality in each action handler:
AccountController.cs
public class AccountController : ApiController
{
public IEnumerable GetAccounts()
{
return DataRepository.Accounts;
}
public Account GetAccount(int accountId)
{
Account result = DataRepository.Accounts.SingleOrDefault(acc =>
acc.AccountId == accountId);
if (result == null)
{
throw new HttpResponseException(HttpStatusCode.NotFound);
}
return result;
}
}



Objective 4.1: Design a Web API

CHAPTER 4

297

CustomerController.cs
public class CustomerController : ApiController
{
public IEnumerable GetCustomers(int accountId)
{
return DataRepository.Customers.Where(cust =>
cust.AccountId == accountId);
}
public IEnumerable SearchCustomers(string lastName)
{
return DataRepository.Customers.Where(cust =>
cust.LastName.ToLower().Contains(lastName.ToLower()));
}
}

EXAM TIP

If the query parameters don’t return a matching value, you have several ways to respond, just
as you would any other query. Although you can opt to return a null value, a more elegant
and expressive means is to throw an HttpResponseException. The HttpResponseException
class has two overloads you can use: The first is to specify an HttpStatusCode enumeration
value, and the second is an HttpResponseMessage. The HttpStatusCode enumeration provides several common and intuitive codes, and in this case, the value of NotFound fits both
logically and mechanically. Make sure that you understand how to use HttpStatusCode for
the exam to return meaningful responses to the client.

The choice about which methods to support and how methods return data depends on
the requirements of the application. After this is all in place, everything is ready to be used.
To access one of the model items, you simply need to reference it by a uniform resource
identifier (URI). In this example, assuming that you host your Web API in the development
web server that is installed with Visual Studio, you can retrieve the Accounts by navigating
to http://localhost:PORTNUMBER/api/Account in your browser. Alternatively, you can also
configure IIS to host these services as you would any other web application. You can navigate
to http://localhost:PORTNUMBER/api/Account?accountId=1 to use querystring parameters to
pass values in for the parameters of your methods.
EXAM TIP

Experiment with calling your Web API by accessing all action methods through their URL.
Try passing different values for parameters such as accountId. Also pass an invalid value so
you get back an HTTP 404 error (the result of HttpResponseException’s HttpStatusCode).

298

CHAPTER 4

Creating and consuming Web API-based services