Unfortunately there was only a textual description of service, nothing I could consume with the Java client tools I have been working with. But I though it would be an interesting experiment to try to document an existing service from scratch.
The first thing I did was to get an example of the data that the service would respond with and run it through a JSON->JSON Schema tool. I used JSONSchema.net which gave me a rough v3 JSON Schema; but it wasn't able to take into account elements that are reused. A little bit of hand editing later I ended up with three JSON Schema files, one for the forecast itself and one for a list of weather details and and one for each particular data point.
From there is was pretty simple to read the developer documentation and write up a simple WADL to describe the two resources provided by the service. Luckily Jason LaPort from the DarkSkys was on hand to fix a few mistake and generally verify my description.
Once I had this all in place I of course found a couple of bugs in my own code, so it was time to update and fix wadl.java.net and release a 1.1.5 version with a revised depdency on the jsonschema2pojo project. This is why a little bit of adhoc expert testing pay dividends.
So taking the WADL from github it is possible to generate a nice clean Java API using the wadl.java.net generator. I won't reproduce the steps to generate the client here, but this is the end result and the kind of code you can get out of it.
// Create a Jersey client and setup for POJO JSON mapping
ClientConfig cc = new DefaultClientConfig();
cc.getFeatures().put(JSONConfiguration.FEATURE_POJO_MAPPING, true);
Client c = Client.create(cc);
// Get current weather for location and check for any alerts
Forecast f = ApiForecastIo_Forecast
.apikey(c, "xxxxxxx") // Get own key from developer.forecast.io
.latitudeLongitude(51.32d, -1.244d) // Some location near where I live
.getAsForecast(
null, // Not JSONP
Units.SI, // Return values in SI units
"hourly,minutely,daily,flags"); // Just return current weather and any alerts
// Output a summary
System.out.println(
f.getCurrently().getSummary() + " " +
f.getCurrently().getTemperature() + " C");
// Output any alerts
List<Alert> alerts = f.getAlerts();
for (Alert altert : alerts) {
System.out.println(
altert.getTitle() + " " + altert.getUri());
}
The nice thing here was just how pleasantly easy describing a service that already exists was, yes I could have written it by hand in Java; but then when I wanted to move to Jersey 2.x I would have to re-write by hand rather that just regenerating from the metadata to a new technology target. (Also did the same for a BBC REST Schedule API, that is in the same git project)
