HackMD.NET Core Wrapper for a Weather API
Let me guess: You're a C# developer who landed on this page after scouring the internet for Weather API wrappers and finding solutions that work mainly with JavaScript. Well, welcome aboard! In this article, we'll focus on the .NET Core stack using the C# programming language.
Prerequisites
We won't be dealing with advanced algorithms or techniques of the C# language here. However, you must be familiar with the basics of object-oriented programming (OOP) concepts, basic unit testing, and creating a project inside Visual Studio.
We'll be making a class library project and using it in our different projects within a Visual Studio solution. The example here is as-is. It has not been tested in any production environment and has been created for educational purposes only. But, of course, it's up to you if you want to extend or use this example.
For this tutorial, we will be using the free Tomorrow.io Weather API. This API provider has a lot of great features to offer, like:
- A weather-intelligence platform
- Weather timelines and trendlines
- Core weather data layers
- 5-day weather forecast
- 6 hours of historical weather data
- One automatically monitored location
- One weather-based alert
The API has many more capabilities as well. However, as we're using the free version, we'll stick to the above features.
1. Project Setup
We first created a Visual Studio blank solution in our project setup, named it "Weather.Solution", and added more projects as needed.
You'll see that inside our solution, we have created a class library project (Weather.ApiWrapper), unit test project (WeatherApiWrapper.Test), and console application (ConsoleWeatherApp1). Each of these projects is created to serve its purpose.
The following is our solution-project structure.
2. Weather API Configuration Settings
appSettings.json
Inside this file, you'll see the configuration representing the arguments that need to be passed to the TomorrowIO Weather API. These values will be created on your profile, and everything is available in the documentation. So, you need to register on the TomorrowIO site and get an API key to use.
It is also important to mention that these keys/properties are required when requesting new weather information: the API key, location, and fields. Without these, the API will return an exception.
Let's see the sample code below.
For the location coordinates, you can use the Locations page of Tomorrow.io. You can then create a new location there and copy the coordinates.
3. WeatherSettings.cs
I know what you're thinking: How are we going to read the JSON configuration file? This third file–-WeatherSettings.cs–-is for that.
It uses the ConfigurationBuilder class to build and get the settings inside our JSON file. There is a public method that will help you get the specific section and property of the WeatherSettings inside the JSON file.
Let's see the sample code below.
4. TestWeatherSettings.cs
To be sure that we can retrieve our configuration, we need to test it. This file serves that purpose. See the code sample below. The test explorer shows that all tests pass.
5. Weather API Parameters
We need to get the proper values of our parameters to send them to the TomorrowIO Weather API. Therefore, once we retrieve the values on our configuration file, we need to represent, validate (if required), and convert those values into one URL string.
In other words, we need to get all the possible values inside our configuration file and build a URL string that will represent the whole configuration so we can pass it to the TomorrowIO API.
The interface, IWeatherParameters, will get the values coming from our configuration file.
Before moving on, let's see the sample code of the WeatherParameter class.
The GetUri() method returns the string URL that we need. It works by looping through all the class instance properties and checking whether they are required. If it is required, it will be included in the URL.
That's why you'll see the attribute [WeatherParameterRequired(true)] and set the property to 'if required'.
Let's see the code sample of our WeatherParameterRequiredAttribute.
6. Consuming/Calling the TomorrowIO API
To call the TomorrowIO Weather API, we need the Http Client class to make an HTTP request. And, of course, we need the URL generated from the WeatherParameter. That's why we have two private members inside the WeatherApi class.
Let's see the sample code below.
Once we combine these two inside our class, we can request new weather information.
As you can see, the GetResult method is where all the magic happens. You'll be able to see the data returned by the TomorrowIO Weather API.
As you see, we're now getting the correct JSON data from our provider. We can use this in any project to include the new weather information. But, of course, it's up to you how you represent your data in your application's UI (user interface).
Lastly, if you want to run the test of this wrapper, you can run the TestWeatherApiWrapper. Thereafter, you can debug it thoroughly.
Let's see the sample code of the TestWeatherApiWrapper.
7. Using the Custom Built Library Wrapper Weather API
Easy, isn't it? We need to have a client-side that will request new weather information for the moment of truth. For this purpose, our project has a console application named "ConsoleWeatherApp1" that will show us how to use our customized weather API efficiently.
Finally, we have installed the package "Microsoft.AspNetCore.Mvc.NewtonsoftJson" in this project to see good JSON formatting when printing the JSON data in a console window.
You will now see the following output.
If you're interested, you can create a new web application inside your solution. Add a reference to this class library, and try it yourself. Please let me know what happens in the comments below.
Summary
As you can see, it's not hard to create a custom weather API using the .Net Core framework and C# language.
We started by seeing the structure of the solution and the different projects inside it. Then we established the classes that will get the configuration and built the values to generate a URL string. Finally, we made an HTTP request by passing the URL string and extracting weather data from the TomorrowIO Weather API represented as a JSON string.
I hope you have enjoyed this post as I have enjoyed writing it. Until next time, happy programming! Stay tuned for more.
