Next in our series of the “Hello World of APIs” we are looking at
Yahoo WeatherTrack this API, a very popular API that provides the latest
weather information. As with our previous tutorials, we will focus on
detailing what a developer needs to know in order to understand the API
and build an application that integrates with it.
In this tutorial we’ll be building our application using JavaScript; this is in response to feedback from previous tutorials, which indicated JavaScript was the most important programming language to cover in the next article. This tutorial will follow the same format as the previous tutorial, walking through the steps required to integrate with the Yahoo Weather! API. In the course of the tutorial the following topics will be discussed:
In terms of choosing a programming language, using JavaScript to consume APIs is a fairly obvious choice; it is hugely popular, with a runtime environment present in every browser. In the past JavaScript was almost exclusively a client-side language, but over the last few years increasing numbers of server-side runtimes and application frameworks have become available (Node.js being the standout example). Implicit in its popularity is support for making calls to APIs over HTTP. Every JavaScript implementation and framework has the capability to directly call a HTTP endpoint and interpret the response when encoded in formats such as XML and JSON, and there are JavaScript libraries available for the majority of popular APIs.
However, there are some considerations developers should be aware of when using JavaScript to consume APIs in the browser. The most of important of these is Cross-Origin Request Sharing, or CORS for short. CORS is a security mechanism implemented in all browsers that prevents JavaScript code from calling a HTTP endpoint different from the location the page originated from: The idea is to prevent miscreants hijacking or injecting calls to other sites. CORS is implemented using an exchange of HTTP headers, and APIs that are served over HTTP must provide CORS support if they wish to provide support to JavaScript applications.
When developing a client-side application that consumes an external API i.e. from a different location to the one the page was served from, developers must ensure that CORS support is available for their application to work. You of course have the option of implementing JSONP, another mechanism for making cross origin requests, but this is generally considered to have security implications and should be avoided unless you are using it with trusted services.
A pure client-side JavaScript application executed in the browser is also, generally, an insecure choice when an API is consumed that implements any sort of credential-based security to authenticate the application, such as an API key and secret. The credentials to access the API are readily available to any user of the application, and as recent coverage of the Verizon Hum website shows, can easily be sniffed.
You should consider these factors before embarking on writing a JavaScript application. You also want to consider the overall architecture such as what functionality makes sense being implemented in the browser, and what may be better implemented server-side. To support this tutorial we have developed an application that is implemented almost entirely on the client, using a number of frameworks to help us. We’ll discuss why we were able to take this approach below.
Yahoo provides information on the Weather API at the Yahoo Developer Network (YDN) site. The core documentation is freely available to read without a Yahoo account, but a developer must register for a YDN account if they call a Yahoo API that requires the use of a client ID and secret.
Yahoo organizes information on the Weather API into the following sections:
The Get Started page provides the developer with a simple overview of what they need to the do to start developing against the Weather API. This includes the following:
However, developers have the option of using YQL, and given that the code snippets mentioned above were created using YQL this appears to be Yahoo’s preferred version of the API. In order to use the YQL interface developers should refer to the main YQL page instead.
You can also use the YQL console to help you create YQL queries that you can use in your Weather API calls, making queries against the weather.forecast table. There is no API description specification so understanding the API relies on using examples in the console to elicit an understanding of the responses.
In this tutorial we’ll be building our application using JavaScript; this is in response to feedback from previous tutorials, which indicated JavaScript was the most important programming language to cover in the next article. This tutorial will follow the same format as the previous tutorial, walking through the steps required to integrate with the Yahoo Weather! API. In the course of the tutorial the following topics will be discussed:
- Application Infrastructure Choices – Why JavaScript?
- Understanding the API – API types, security, etc.;
- Sending the request – Walkthrough of our example application;
Application Infrastructure Choices – Why JavaScript?
In terms of choosing a programming language, using JavaScript to consume APIs is a fairly obvious choice; it is hugely popular, with a runtime environment present in every browser. In the past JavaScript was almost exclusively a client-side language, but over the last few years increasing numbers of server-side runtimes and application frameworks have become available (Node.js being the standout example). Implicit in its popularity is support for making calls to APIs over HTTP. Every JavaScript implementation and framework has the capability to directly call a HTTP endpoint and interpret the response when encoded in formats such as XML and JSON, and there are JavaScript libraries available for the majority of popular APIs.
However, there are some considerations developers should be aware of when using JavaScript to consume APIs in the browser. The most of important of these is Cross-Origin Request Sharing, or CORS for short. CORS is a security mechanism implemented in all browsers that prevents JavaScript code from calling a HTTP endpoint different from the location the page originated from: The idea is to prevent miscreants hijacking or injecting calls to other sites. CORS is implemented using an exchange of HTTP headers, and APIs that are served over HTTP must provide CORS support if they wish to provide support to JavaScript applications.
When developing a client-side application that consumes an external API i.e. from a different location to the one the page was served from, developers must ensure that CORS support is available for their application to work. You of course have the option of implementing JSONP, another mechanism for making cross origin requests, but this is generally considered to have security implications and should be avoided unless you are using it with trusted services.
A pure client-side JavaScript application executed in the browser is also, generally, an insecure choice when an API is consumed that implements any sort of credential-based security to authenticate the application, such as an API key and secret. The credentials to access the API are readily available to any user of the application, and as recent coverage of the Verizon Hum website shows, can easily be sniffed.
You should consider these factors before embarking on writing a JavaScript application. You also want to consider the overall architecture such as what functionality makes sense being implemented in the browser, and what may be better implemented server-side. To support this tutorial we have developed an application that is implemented almost entirely on the client, using a number of frameworks to help us. We’ll discuss why we were able to take this approach below.
Understanding the API
Yahoo provides information on the Weather API at the Yahoo Developer Network (YDN) site. The core documentation is freely available to read without a Yahoo account, but a developer must register for a YDN account if they call a Yahoo API that requires the use of a client ID and secret.
Yahoo organizes information on the Weather API into the following sections:
- Get Started
- Documentation
- Create An App
Get Started
The Get Started page provides the developer with a simple overview of what they need to the do to start developing against the Weather API. This includes the following:
- A link to the Create an App page that allows a developer to get the Client ID and Secret required to access the API. Note that in the case of the Weather API this is not required for personal, non-commercial use, but an Application ID is required to access the Yahoo GeoPlanet API, which, in some cases the RSS version of the Weather API relies on (more on this below).
- Code snippets for different languages, including JavaScript. These code snippets use Yahoo Query Language (YQL) as the basis for the API call, but developers can use HTTP addresses as well (the RSS version of the API), which is described in the documentation section.
- A link to the YDN forums.
- Links to important documentation, including Yahoo’s attribution guidelines that detail how a developer should attribute the fact they are using the Weather API in their application (which they must do or risk violating the terms of use for Yahoo APIs).
Documentation
The documentation page covers only the format of the RSS version of the Weather API, including the required query parameters and the response structure. As mentioned above, you’ll also need to read the GeoPlanet API documentation in order to understand how to retrieve a WOEID (Where On Earth ID) that the RSS version relies on for looking up the weather for a given place.However, developers have the option of using YQL, and given that the code snippets mentioned above were created using YQL this appears to be Yahoo’s preferred version of the API. In order to use the YQL interface developers should refer to the main YQL page instead.
You can also use the YQL console to help you create YQL queries that you can use in your Weather API calls, making queries against the weather.forecast table. There is no API description specification so understanding the API relies on using examples in the console to elicit an understanding of the responses.
Create An App
Yahoo requires a developer to create an app for some of their APIs which is essentially a logical entity registered to their Yahoo user account and used as an internal identifier for the application accessing the API. As mentioned above, creating an app is not required to access the RSS version of the Weather API per se, but developers will need to access the GeoPlanet API to look up the WOEID so using this feature is required. Once you’ve created an app you’ll have access to the app overview page that contains the application ID you need to access the GeoPlanet API, as shown below. However, if you use the YQL interface to query the Weather API you do not need to create an app. YQL queries can be performed without an authentication.
To
make a request for the forecast in a given location is relatively
trivial. In the example below, we defined a function to retrieve the
weather for London using the following YQL query:
The query is passed as an argument to the API. On response, the function displays an alert with the temperature:
- select * from weather.forecast where woeid in (select woeid from geo.places(1) where text=’London, GB’)&format=json
The query is passed as an argument to the API. On response, the function displays an alert with the temperature:
function getWeatherDemo() {
$.get('https://query.yahooapis.com/v1/public/yql?q=select * from weather.forecast ' +
'where woeid in (select woeid from geo.places(1) where text="London")&format=json', function (data) {
console.log(data);
alert("The temperatute in London is " +
data.query.results.channel.item.condition.temp +
data.query.results.channel.units.temperature
);
});
}
On loading the page, the user is presented with a blank page and a text box in the navigation bar. They enter a place and click ‘Get Forecast’ (note the ‘Powered by Yahoo!’ logo that has been implemented as per the attribution guidelines). If the place requested is found then the current weather is displayed, with a forecast below.
As one can see from our sample application, building a pure JavaScript application to consume the Yahoo! Weather API is a trivial task and can be accomplished with very little code. However, when integrating with APIs in browser-based applications developers should think carefully about their choices and the implications for application and API security discussed above. Generally speaking, any confidential information such as API keys and secrets should be implemented away from the browser on a server that is under the control of the developer. With this approach in mind, developers will be able to develop their own exciting JavaScript applications that can mash up all manner of APIs, secured or otherwise.
$.get('https://query.yahooapis.com/v1/public/yql?q=select * from weather.forecast ' +
'where woeid in (select woeid from geo.places(1) where text="London")&format=json', function (data) {
console.log(data);
alert("The temperatute in London is " +
data.query.results.channel.item.condition.temp +
data.query.results.channel.units.temperature
);
});
}
For our sample application the use of YQL suited our purposes better than the RSS version of the Weather API. We built the app to run entirely in the browser, we looked to have CORS support and the YQL endpoint provides this. We could have used JSONP with the RSS version of course, but this would have been more challenging and created a more complex example for limited benefit. Using YQL also meant there was no need for an application ID, and thus no security implications on holding this confidential information in the browser.
Using this example function as a starting point, we created a very simple application that implements two features:
It allows a user to enter a location in a text box.
When submitted, the weather forecast for the place in question is retrieved and displayed.
The sample application, hosted on Github implemented a number of frameworks to keep our application simple:
Using this example function as a starting point, we created a very simple application that implements two features:
It allows a user to enter a location in a text box.
When submitted, the weather forecast for the place in question is retrieved and displayed.
The sample application, hosted on Github implemented a number of frameworks to keep our application simple:
- JQuery, where we used Ajax to make calls to the API and selectors to update the HTML with data from the API.
- Bootstrap, to quickly create an appealing looking page.
- Bootbox, for easy to implement modal dialogs.
On loading the page, the user is presented with a blank page and a text box in the navigation bar. They enter a place and click ‘Get Forecast’ (note the ‘Powered by Yahoo!’ logo that has been implemented as per the attribution guidelines). If the place requested is found then the current weather is displayed, with a forecast below.
The HTML for display is then built dynamically. If you prefer, there are plenty of JavaScript frameworks that could do this for you out-of-the-box, such as Angular or React. An alternative in a server-side implementation would be to use a templating language like Swig to do this:
function getWeather() {
var location = $('#city').val();
$.get('https://query.yahooapis.com/v1/public/yql?q=select * from weather.forecast where woeid in (select woeid from geo.places(1) where text="' + location + '")&format=json', function (data) {
/* Check that a place was found (we'll just grab the first) */
if (data.query.results === null) {
bootbox.alert("Location not found: " + location + "!");
} else {
$('.jumbotron').html('<h2>' + data.query.results.channel.item.title + '</h2>' +
data.query.results.channel.item.description)
$('.container').show();
}
});
}
var location = $('#city').val();
$.get('https://query.yahooapis.com/v1/public/yql?q=select * from weather.forecast where woeid in (select woeid from geo.places(1) where text="' + location + '")&format=json', function (data) {
/* Check that a place was found (we'll just grab the first) */
if (data.query.results === null) {
bootbox.alert("Location not found: " + location + "!");
} else {
$('.jumbotron').html('<h2>' + data.query.results.channel.item.title + '</h2>' +
data.query.results.channel.item.description)
$('.container').show();
}
});
}
If the place is not found an alert dialog is displayed:
Summary
As one can see from our sample application, building a pure JavaScript application to consume the Yahoo! Weather API is a trivial task and can be accomplished with very little code. However, when integrating with APIs in browser-based applications developers should think carefully about their choices and the implications for application and API security discussed above. Generally speaking, any confidential information such as API keys and secrets should be implemented away from the browser on a server that is under the control of the developer. With this approach in mind, developers will be able to develop their own exciting JavaScript applications that can mash up all manner of APIs, secured or otherwise.
No comments:
Post a Comment
Note: only a member of this blog may post a comment.