API Academy

Sponsored by Layer7

The Next Level in Web APIs

By Ronnie MitraPosted on

A new series of articles explores API description, discovery and profiles

I’m very proud to announce that InfoQ has just launched a new series that I helped edit. The series, called Description, Discovery & Profiles: The Next Level in Web APIs, features a collection of excellent contributing authors including API Academy/CA’s own Ronnie Mitra, Mike Stowe from Mulesoft, Kin Lane of API Evangelist fame and Mark Foster from Apiary. It also includes interviews with Swagger creator Tony Tam and Profile RFC editor Erik Wilde. And it’s packed with material covering what I think are three key patterns/technologies in the Web API space:

Description â€œThe ability to easily describe APIs including implementation details such as resources and URLs, representation formats (HTML, XML, JSON, etc.), status codes and input arguments in both a human- and machine-readable form. There are a few key players setting the pace here.â€

Discovery â€œSearching for, and selecting Web APIs that provide the desired service (e.g. shopping, user management, etc.) within specified criteria (e.g. uptime, licensing, pricing, and performance limits). Right now this is primarily a human-driven process but there are new players attempting to automate selected parts of the process.â€

Profiles â€œLong a focus of librarians and information scientists, ‘Profiles’ that define the meaning and use of vocabulary terms carried within API requests and responses are getting renewed interest for Web APIs. Still an experimental idea, there is some evidence vendors and designers are starting to implement support for Web API Profiles.â€

Lots of Vendors & Technologies Here This is a pretty wide-ranging set of topics and lots of vendors and technologies are highlighted over the next seven articles. Some of them include:

And that’s just in the first article of the series!

Here’s a quick rundown of all the articles that will be released between late May and early July…

Description, Discovery & Profiles: A Primer This article takes a look at several formats and key vendors then identifies the opportunities and challenges in this fast-moving portion of the Web API field.

From Doodles to Delivery: An API Design Process Ronnie Mitra investigates what good design is and how using profiles along with an iterative process can help us achieve it.

The Power of RAML Mike Stowe introduces us to the RAML format, reviews available uses and tools then explains why Uri Sarid, the creator of RAML, wanted to push beyond our current understandings and create a way to model APIs before even writing one line of code.

APIs with Swagger: An Interview with Reverb’s Tony Tam I talk to founder and inventor Tony Tam about the history and future of one of the most widely-used API description formats today: Swagger.

The APIs.json Discovery Format: Potential Engine in the API Economy In this piece, Kin Lane describes his APIs.json API discovery format which can provide pointers to available documentation, licensing and pricing for existing Web APIs.

Profiles on the Web: An Interview with Erik Wilde Erik sits down with InfoQ to talk about profiles, description, documentation, discovery, his Sedola project and the future of Web-level metadata for APIs.

Programming with Semantic Profiles: In the Land of Magic Strings, the Profile-Aware is KingMark Foster – one of the editors of the ALPS specification – explains what semantic profiles are and how they can transform the way Web APIs are designed and implemented.

A Resource Guide to API Description, Discovery & Profiles To wrap up the series, we offer a listing of the key formats, specifications, tools and articles on API description, discovery and profiles for the Web.

Looking Forward to the Weekly Releases It was a pleasure working with such a distinguished group of authors and practitioners in this very important space and I am looking forward to the continued releases between late May and early July. I’m also looking forward to feedback and discussion from readers of the series.

The Web is a dynamic and fast-moving space and it should be interesting to keep an eye on this “meta level†of the API ecosystem for some time to come.

(This post was originally published on my personal blog.)