Fun with APIs

The next Brighton Java session is a workshop about building small applications by combining APIs (it’s September 23rd, details and signup on Meetup). I think everyone will able to produce something interesting in a couple of hours, despite Java’s reputation for being being heavyweight (although we might have to skip error handling and testing).

There is a good resource of public APIs on github. The workshop will involve picking two of these APIs and combining them (I’m old enough to remember this being referred to as a mashup). There are particularly interesting possibilities involving time and location, but as a practise example, I combined Kanye.REST‘s random Kanye quotes with cat pictures.

(There is an API endpoint returning random APIs, so I guess you could even produce a service to suggest mashups…)

I’m going to prepare a full worksheet for the event, but in the meantime, here are the simple steps I followed to produce a very simple API:

Set up basic project

I downloaded a Spring Boot guide application to use as a basis and imported this into intellij. This gaves me a build system with no need to mess around. When importing the project, I made sure to use external sources for the build tooling, which set all the libraries appropriately.

Add dependencies

The example I worked with used REST, so I added the Jersey libraries to gradle.

compile 'org.glassfish.jersey.containers:jersey-container-servlet:2.25.1'
 compile group: 'org.json', name: 'json', version: '20190722'
 compile 'org.glassfish.jersey.inject:jersey-hk2:2.28'
 compile 'org.glassfish.jersey.media:jersey-media-json-jackson:2.22'

EDIT – 23/9 – Jersey is probably not the best library to use for REST APIs. Spring includes RestTemplate, which also has some great testing support in TestRestTemplate. However, it does not seem to have a user-agent set, which upsets a lot of servers. So I am going to use Jersey for this demonstration to make the code simpler, although I would use probably use RestTemplate if i was going into production. Thanks to David Pashley for raising and discussing this issue with me.

Add classes to manage responses

Next I made some classes to map the responses. This produces a coupling between the endpoint and the code. I’m not sure if there is a way to make this more flexible, but as this is a quick-and-dirty demo, it will do.

import com.fasterxml.jackson.annotation.JsonProperty;

 public class Quote {
 @JsonProperty("quote") 
  public String quote; 

  public Quote() { } 
  public String getQuote() {
     return quote;
 }
}

Add the basic code

I then edited the HelloController class within the downloaded Spring Boot project, and wrote some quick code for downloading the APIs. This is a very long way from production quality, with no error management, but it does the job:

package hello;

import javax.ws.rs.core.MediaType;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.RequestMapping;
import javax.ws.rs.client.Client;
import javax.ws.rs.client.ClientBuilder;
import javax.ws.rs.client.WebTarget;

@RestController
public class HelloController {
 @RequestMapping("/")
 public String index() {
     String responseString;
     String location = "";
     try {
         Client client = ClientBuilder.newClient();
         WebTarget target2 = client.target("https://api.kanye.rest");
         Quote response2 = target2.request(MediaType.APPLICATION_JSON_TYPE).get(Quote.class);
         responseString = response2.getQuote();
         WebTarget target = client.target("https://aws.random.cat/meow");
         CatPic response1 = target.request(MediaType.APPLICATION_JSON_TYPE).get(CatPic.class);
         location = response1.getLocation();
     } catch (Throwable t) {
         return t.getMessage();
     }
     return "<h1>" + responseString + "</h1><img src=\"" + location + "\"/>";
 }
}

At this point the code can be executed from the command line with the command ‘gradle bootRun’.

Some other useful resources

• A comprehensive guide to APIs
• Some interesting posts from have-i-been-pwned about APIs, one on adding authetication to APIs], and another on pragmatic versioning.
• An example using JAX-RS and Jersey to read XML/JSON apis
• Another Jersey/REST example