How To Create A Web Api In Visual Studio 2010

This tutorial shows how to call a web API from a .NET application, using HttpClient .

In this tutorial, we will write an app that consumes the following web API.

Action	HTTP method	Relative URI
Get a product by ID	GET	/api/products/id
Create a new product	POST	/api/products
Update a product	PUT	/api/products/id
Delete a product	DELETE	/api/products/id

To learn how to implement this API on the server, using ASP.NET Web API, see Creating a Web API that Supports CRUD Operations.

For simplicity, the client application in this tutorial is a Windows console application.HttpClient is also supported for Windows Phone and Windows Store apps. For more information, see Writing Web API Client Code for Multiple Platforms Using Portable Libraries

Create the Console Application

Start Visual Studio and selectNew Project from theStart page. Or, from theFile menu, selectNew and thenProject.

In theTemplates pane, selectInstalled Templates and expand theVisual C# node. UnderVisual C#, selectWindows. In the list of project templates, selectConsole Application. Name the project and clickOK.

Install the Web API Client Libraries

Use NuGet Package Manager to install the Web API Client Libraries package.

From theTools menu, selectLibrary Package Manager, then selectPackage Manager Console. In the Package Manager Console window, type the following command:

          Install          -          Package                              Microsoft          .          AspNet          .          WebApi          .          Client

Add the Model Class

Add the following class to the application:

          class                              Product                              {                              public                              string                              Name                              {                              get          ;                              set          ;                              }                              public                              double                              Price                              {                              get          ;                              set          ;                              }                              public                              string                              Category                              {                              get          ;                              set          ;                              }                              }

This class matches the data model used in the "ProductStore" Web API project.

Create and Initialize HttpClient

          using                              System          ;                              using                              System          .          Net          .          Http          ;                              using                              System          .          Net          .          Http          .          Headers          ;                              using                              System          .          Threading          .          Tasks          ;                              namespace                              ProductStoreClient                              {                              class                              Program                              {                              static                              void                              Main          ()                              {                              RunAsync          ().          Wait          ();                              }                              static                      async                    Task                              RunAsync          ()                              {                              using                              (          var                      client                    =                              new                              HttpClient          ())                              {                              // TODO - Send HTTP requests                              }                              }                              }                              }

Notice that the Main function calls an async method namedRunAsync and then blocks untilRunAsyncc completes. Many of theHttpClient methods are async, because they perform network I/O. In theRunAsync method, I'll show the correct way to invoke those methods asynchronously. It's OK to block the main thread in a console application, but in a GUI application, you should never block the UI thread.

Theusing statement creates anHttpClient instance and disposes it when the instance goes out of scope. Inside the using statement, add the following code:

          using                              (          var                      client                    =                              new                              HttpClient          ())                              {                              // New code:                      client          .          BaseAddress                              =                              new                              Uri          (          "http://localhost:9000/"          );                      client          .          DefaultRequestHeaders          .          Accept          .          Clear          ();                      client          .          DefaultRequestHeaders          .          Accept          .          Add          (          new                              MediaTypeWithQualityHeaderValue          (          "application/json"          ));                              }

This code sets the base URI for HTTP requests, and sets the Accept header to "application/json", which tells the server to send data in JSON format.

Getting a Resource (HTTP GET)

The following code sends a GET request for a product:

          using                              (          var                      client                    =                              new                              HttpClient          ())                              {                      client          .          BaseAddress                              =                              new                              Uri          (          "http://localhost:9000/"          );                      client          .          DefaultRequestHeaders          .          Accept          .          Clear          ();                      client          .          DefaultRequestHeaders          .          Accept          .          Add          (          new                              MediaTypeWithQualityHeaderValue          (          "application/json"          ));                              // New code:                              HttpResponseMessage                      response                    =                      await client          .          GetAsync          (          "api/products/1"          );                              if                              (          response          .          IsSuccessStatusCode          )                              {                              Product                      product                    =                      await response          .          Content          .          ReadAsAsync          >          Product          >();                              Console          .          WriteLine          (          "{0}\t${1}\t{2}"          ,                      product          .          Name          ,                      product          .          Price          ,                      product          .          Category          );                              }                              }

TheGetAsync method sends the HTTP GET request. The method is asynchronous, because it performs network I/O. Theawait keyword suspends execution until the asynchronous method completes. When the method completes, it returns anHttpResponseMessage that contains the HTTP response.

If the status code in the response is a success code, the response body contains the JSON representation of a product. CallReadAsAsync to deserialize the JSON payload to aProduct instance. TheReadAsync method is asynchronous because the response body can be arbitrarily large.

A note about error handling:HttpClient does not throw an exception when the HTTP response contains an error code. Instead, theIsSuccessStatusCode property isfalse if the status is an error code.

If you prefer to treat HTTP error codes as exceptions, call theEnsureSuccessStatusCode method. This method throws an exception if the response status is not a success code:

          try                              {                              HttpResponseMessage                      response                    =                      await client          .          GetAsync          (          "api/products/1"          );                      resp          .          EnsureSuccessStatusCode          ()          ;                              // Throw if not a success code.                              // ...                              }                              catch                              (          HttpRequestException                      e          )                              {                              // Handle exception.                              }

HttpClient can can throw exceptions for other reasons as well — for example, if the request times out.

Using Media-Type Formatters in ReadAsync

WhenReadAsAsync is called with no parameters, the method uses the default set of media-type formatters to read the response body. The default formatters support JSON, XML, and Form-url-encoded data.

You can also specify a list of formatters, which is useful if you have a custom media-type formatter:

          var                      formatters                    =                              new                              List          <          MediaTypeFormatter          >()                              {                              new                              MyCustomFormatter          (),                              new                              JsonMediaTypeFormatter          (),                              new                              XmlMediaTypeFormatter          ()                              };                      resp          .          Content          .          ReadAsAsync          <          IEnumerable          <          Product          >>(          formatters          );

Creating a Resource (HTTP POST)

The following code sends a POST request that contains aProduct instance in JSON format:

          // HTTP POST                              var                      gizmo                    =                              new                              Product          ()                              {                              Name                              =                              "Gizmo"          ,                              Price                              =                              100          ,                              Category                              =                              "Widget"                              };                      response                    =                      await client          .          PostAsJsonAsync          (          "api/products"          ,                      gizmo          );                              if                              (          response          .          IsSuccessStatusCode          )                              {                              // Get the URI of the created resource.                              Uri                      gizmoUrl                    =                      response          .          Headers          .          Location          ;                              }

ThePostAsJsonAsync method serializes an object to JSON and then sends the JSON payload in a POST request. To send XML, use thePostAsXmlAsync method. To use another formatter, callPostAsync:

          MediaTypeFormatter                      formatter                    =                              new                              MyCustomFormatter          ();                      response                    =                      await client          .          PostAsync          (          "api/products"          ,                      gizmo          ,                      formatter          );

Updating a Resource (HTTP PUT)

The following code sends a PUT request to update a product.

          // HTTP PUT                      gizmo          .          Price                              =                              80          ;                              // Update price                      response                    =                      await client          .          PutAsJsonAsync          (          gizmoUrl          ,                      gizmo          );

ThePutAsJsonAsync method works likePostAsJsonAsync, except that it sends a PUT request instead of POST.

Deleting a Resource (HTTP DELETE)

The following code sends a DELETE request to delete a product.

          // HTTP DELETE                      response                    =                      await client          .          DeleteAsync          (          gizmoUrl          );

Like GET, a DELETE request does not have a request body, so you don't need to specify JSON or XML format.

Complete Code Example

Here is the complete code for this tutorial. The code is very simple and doesn't show error handling, but it shows the basic CRUD operations usingHttpClient.

          using                              System          ;                              using                              System          .          Net          .          Http          ;                              using                              System          .          Net          .          Http          .          Headers          ;                              using                              System          .          Threading          .          Tasks          ;                              namespace                              ProductStoreClient                              {                              class                              Product                              {                              public                              string                              Name                              {                              get          ;                              set          ;                              }                              public                              double                              Price                              {                              get          ;                              set          ;                              }                              public                              string                              Category                              {                              get          ;                              set          ;                              }                              }                              class                              Program                              {                              static                              void                              Main          ()                              {                              RunAsync          ().          Wait          ();                              }                              static                      async                    Task                              RunAsync          ()                              {                              using                              (          var                      client                    =                              new                              HttpClient          ())                              {                      client          .          BaseAddress                              =                              new                              Uri          (          "http://localhost:9000/"          );                      client          .          DefaultRequestHeaders          .          Accept          .          Clear          ();                      client          .          DefaultRequestHeaders          .          Accept          .          Add          (          new                              MediaTypeWithQualityHeaderValue          (          "application/json"          ));                              // HTTP GET                              HttpResponseMessage                      response                    =                      await client          .          GetAsync          (          "api/products/1"          );                              if                              (          response          .          IsSuccessStatusCode          )                              {                              Product                      product                    =                      await response          .          Content          .          ReadAsAsync          <          Product          >();                              Console          .          WriteLine          (          "{0}\t${1}\t{2}"          ,                      product          .          Name          ,                      product          .          Price          ,                      product          .          Category          );                              }                              // HTTP POST                              var                      gizmo                    =                              new                              Product          ()                              {                              Name                              =                              "Gizmo"          ,                              Price                              =                              100          ,                              Category                              =                              "Widget"                              };                      response                    =                      await client          .          PostAsJsonAsync          (          "api/products"          ,                      gizmo          );                              if                              (          response          .          IsSuccessStatusCode          )                              {                              Uri                      gizmoUrl                    =                      response          .          Headers          .          Location          ;                              // HTTP PUT                      gizmo          .          Price                              =                              80          ;                              // Update price                      response                    =                      await client          .          PutAsJsonAsync          (          gizmoUrl          ,                      gizmo          );                              // HTTP DELETE                      response                    =                      await client          .          DeleteAsync          (          gizmoUrl          );                              }                              }                              }                              }                              }