Recently, Marvel has made available a public API and a RESTful service which provides access to their comics metadata.
Roberto Medrano, Executive VP at SOA Software, considers that web APIs will see a “massive adoption” in 2014 and the following years. Not only that APIs will drive the development of mobile applications, but mobile + cloud make for a great combination: “when APIs work through the cloud, their ability to connect and deliver is made exponentially easier than having to do it through traditional platforms.” Also, software-defined data centers will rely on APIs, the “Internet of Things will become the API of Things”, SOA and APIs will be more and more seen as complementary, and event REST will evolve through the contribution of “new standards like WADL, Swagger, RAML and others, all due to their flexibility and that these will fill in holes left by REST and the deficiencies it has with defining service descriptions,” according to Medrano.
It is no wonder that even the Marvel comics and characters can now be accessed via a public API. Beside their attraction from an entertainment perspective, the Marvel Comics API is an example of how a web API should be designed. Marvel runs a RESTful service providing JSON responses to HTTP requests, the endpoints currently supporting only the verb GET.
The resources in Marvel’s API are:
- Comics: individual print and digital comic issues, collections and graphic novels. For example: Amazing Fantasy #15.
- Comic series: sequentially numbered (well, mostly sequentially numbered) groups comics with the same title. For example, Uncanny X-Men.
- Comic stories: indivisible, reusable components of comics. For example, the cover from Amazing Fantasy #15 or the origin of Spider-Man story from that comic.
- Comic events and crossovers: big, universe-altering storylines. For example, Infinity
- Creators: women, men and organizations who create comics. For example, Jack Kirby.
- Characters: the women, men, organizations, alien species, deities, animals, non-corporeal entities, trans-dimensional manifestations, abstract personifications, and green amorphous blobs which occupy the Marvel Universe (and various alternate universes, timelines and altered realities therein). For example, Spider-Man.
An example of a request for the Avengers character looks like this:
http://gateway.marvel.com:80/v1/public/characters/1009165?apikey=xxxxx
And the shortened response is:
{
"code": 200,
"status": "Ok",
"etag": "e52e95f71334d797c3c2d0cf144bcc3e611718db",
"data": {
"offset": 0,
"limit": 20,
"total": 1,
"count": 1,
"results": [
{
"id": 1009165,
"name": "Avengers",
"description": "Earth's Mightiest Heroes joined forces to take on threats
that were too big for any one hero to tackle.
With a roster that has included Captain America, Iron Man, Ant-Man, Hulk, Thor, Wasp
and dozens more over the years, the Avengers have come to be regarded as Earth's No. 1 team.",
…
}
]
}
}
The Marvel Comics API supports authentication, versioning, retrieving collections of resources or resources specified by ID, cross-origin requests, compression and eTags used to avoid returning a response twice if the content has not changed since the first request. The database includes a large collections of images as the one shown above, which was retrieved using the path provided in the Avengers response. Developers are limited to 1,000 API calls/account.
Apigee’s ebook “Web API Design: Crafting Interfaces that Developers Love” provides detailed advice on designing web APIs.