6/28/2017 AnthonyBaker:HowtoConsumeaJSONRESTAPIin.

NET

How to Consume a JSON REST API in .NET

In this article Ill show you how simple it is to consume JSON based APIs from .NET. It requires just
a few lines of code, is straight forward and will work across different types of apps. Ill also show
you how to consume an example API synchronously and asynchronously.

But before, lets talk a bit about the API subject, shall we? (if you are in a hurry, just jump directly
to the code).

Consumingweb servicesand APIs will always be a big topic on our industry.Service oriented
architecturesenable us to create online endpoints to serve many different clients across the digital
world.Application programming interfaces (APIs)are nothing new, they have been with us for a
long time, and have consumed a lot of our efforts to communicate digital systems. However,web
APIsare becoming more and more relevant, since they allows us to communicate thought networks
to serve a wide variety of clients.

Representation State Transfer (REST)design models are the predominant software architecture for
such distributed systems. Most modern web APIs are designed following the REST principles,
resulting in simpler, general, more scalable web services that are easier to consume.

.NET has come a long way in terms of web services architectures. Most of us will remember
traditional ASP.NET services, SOAP based services, WCF services and XMLbased services without too
much excitement. Although they were powerful service oriented technologies and frameworks, not
many will say that they were easy to implement. RESTful services have also become the
predominant model design in .NET, and now more than ever, consuming and exposing RESTful
services relatively easy. However, there seems to be a lot of confusion about how to do such things
in the .NET world!

Consuming JSON RESTful services in .NET

With any new version of the .NET framework, and features, we should revise if we can implement
functionality in a new, easier and/or simpler way. With all the recent updates to the stack, I
wanted to do a review on how to consume JSON APIs from .NET applications. It turns out that there
are a lot of discussions on the matter, different opinions, techniques and samples, but I found it
difficult to find the right answer straight away.

So, to make it clear, easy and concrete, lets build something right away. We will start with a
simple console application project. Fire up Visual Studio (Im using VS 2012), and create a new
console application project.

http://blog.anthonybaker.me/2013/05/howtoconsumejsonrestapiinnet.html 1/8
6/28/2017 AnthonyBaker:HowtoConsumeaJSONRESTAPIin.NET

We will implement a simple Weather API client by using theOpenWeatherMap.org JSON API. The
API will allow us to locate a city location and get the weather forecast information.

Lets create a new class to manage the API client logic. Right click on the project, select Add
>Class. Name it WeatherApiClient.cs.

For simplicity, Ill make the class static, so I can call its methods straight away from the main
program class. We will first implement the synchronous client method.

Create a new void method in the class. Lets call it GetWeatherForecast(). Don;t forget to make it
static.

Ok, so now we need to decide which mechanism are we going to use to consume the API. In .NET
you can use two different classes:WebClientorHttpWebRequest. Without getting into much
detail, the popular opinion is that WebClient provides a simpler and easier implementation, while
HttpWebRequest allows a more granular control over the way requests are executed.

In this case, we will use the WebClient class. It has a method called DownloadString() which
received a string URL and returns a string containing the JSON response. Notice that in order to use
WebClient, you will need to add a reference to System.Net to your project.

To implement this first step, just declare a sample URL (you can check in the OpenWeatherMap
documentation for one). Then create a new WebClient variable and call the DownloadString()
method passing the URL.

http://blog.anthonybaker.me/2013/05/howtoconsumejsonrestapiinnet.html 2/8
6/28/2017 AnthonyBaker:HowtoConsumeaJSONRESTAPIin.NET

At this point, we can call our method from the main program class and put a breakpoint on it, so
we can check the response from the API. Lets do that, and make sure the call is working and you
are getting the JSON response back as a string result.

Let the WebClient make the call and then examine the contents of the response. You should be
able to use the Text Visualizer tool to review the JSON response.

http://blog.anthonybaker.me/2013/05/howtoconsumejsonrestapiinnet.html 3/8
6/28/2017 AnthonyBaker:HowtoConsumeaJSONRESTAPIin.NET

Great. We are actually able to make the call to the API and get the JSON. That was actually quite
easy and straight forward. Just like it should be. Now the question is, what do we do with the
response?

You might just want to store it, or pass it to another client or something long those lines. But
chances are that you actually want to deserialize the response and be able to get an object out of
it, so you can work on it more comfortably. For this, we need a JSON serialization/deserialization
mechanism (which is quite similar to XML serialization/deserialization tools).

There are a couple of libraries you could use. JSON.NET is one of them (checkthis articlefrom
Scott Hanselman on the subject). However, I would rather use something native and avoid adding
dependencies to the solution. It turns out that .NET has a class calledDataContractJsonSerializer,
which conveniently, lets you serialize objects to JSON and deserialize JSON to objects.

Now, we need to specify the type of object we want to use to deserialize our JSON response. You
would normally have to check the JSON structure, and create the corresponding .NET class in your
application, which is honestly, quite tedious. Happily, there is a neat web app
calledjson2csharpthat allows you to enter a JSON string (or a URL to a JSON string), and it will
generate the corresponding C# class for you!

Copy the JSON response you got from the OpenWeatherMap API and paste it in the json2csharp text
field, then click the Generate button.

Stop debugging your Visual Studio solution if you havent done so. In the Visual Studio project,
create a new class and name it WeatherData.cs. Copy the code from json2csharp and paste it in

http://blog.anthonybaker.me/2013/05/howtoconsumejsonrestapiinnet.html 4/8
6/28/2017 AnthonyBaker:HowtoConsumeaJSONRESTAPIin.NET

the new class, without overriding the default class code. Notice that the class generated by
json2csharp contains several class definitions.

The last class generated by json2csharp is actually the root object containing the whole response.
It will contain all the objects within the JSON string. We want this object to be our WeatherData
class. You can rename the RootObject, or copy its properties to our WeatherData class definition.

For each of the generated classes, create a property of the same type in the WeatherData main
class. To enable the DataContractJsonSerializer to use this class for serializing and deserializing,
you need to add the DataContract attribute on the main class, and the DataMember attribute on
each of the main class properties. You will need to add a reference to
System.Runtime.Serialization to your project.

http://blog.anthonybaker.me/2013/05/howtoconsumejsonrestapiinnet.html 5/8
6/28/2017 AnthonyBaker:HowtoConsumeaJSONRESTAPIin.NET

Great. Save the class and go back to our WeatherApiClient class. What we need now is to add the
code to deserialize the JSON response to get a WeatherData object from it.

For this, you will need to add two using clauses: System.Runtime.Serialization.Json for the
DataContractJsonSerializer and System.IO for the MemoryStream we will need.

Declare a new DataContractJsonSerializer passing the WeatherData as the required type. Then
create a MemoryStream object from the string response we obtained before from the API. Finally,
use the ReadObject() method of the serializer to deserialize the JSON response. You should obtain a
nice WeatherData object with all the information we got from the API.

http://blog.anthonybaker.me/2013/05/howtoconsumejsonrestapiinnet.html 6/8
6/28/2017 AnthonyBaker:HowtoConsumeaJSONRESTAPIin.NET

Compile and run the project, using the previous breakpoint. Examine the weatherData object after
deserializing the response. You should see all the weather information in your .NET object!

There you go. That wasnt difficult at all. You have a data class, which was generated almost
entirely for you by json2csharp. Then a main program, where you only had to write one line of
code to call your GetWeatherForecast() method. And the WeatherApiClient class itself is just 30
lines of code, of which 6 lines are actually doing the job (the rest is brackets and definitions).

Here is the main code you need:

1:publicstaticclassWeatherApiClient
2:{
3:publicstaticvoidGetWeatherForecast()
4:{

http://blog.anthonybaker.me/2013/05/howtoconsumejsonrestapiinnet.html 7/8
6/28/2017 AnthonyBaker:HowtoConsumeaJSONRESTAPIin.NET

5:varurl="http://api.openweathermap.org/data/2.1/find/city?lat=51.50853&lon=0.12574&cnt=10
6:
7://SynchronousConsumption
8:varsyncClient=newWebClient();
9:varcontent=syncClient.DownloadString(url);
10:
11://CreatetheJsonserializerandparsetheresponse
12:DataContractJsonSerializerserializer=newDataContractJsonSerializer(
13:using(varms=newMemoryStream(Encoding.Unicode.GetBytes(content)))
14:{
15:varweatherData=(WeatherData)serializer.ReadObject(ms);
16:}
17:}
18:}

Next, Ill publish the follow up article on how to make the API request asynchronously. I plan to
keep working on this topic, and add more popular APIs, including social networks, since Im sure it
would be helpful for many people out there.

You can download the full source code from my Github repositoryhere.

Please take a couple of minutes to leave comments, questions or suggestions. Im more than happy
to get in touch and help you, or learn from whatever you can share.

http://blog.anthonybaker.me/2013/05/howtoconsumejsonrestapiinnet.html 8/8