The Next Level in Web APIs

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 King Mark 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.)

The Author

Mike Amundsen

Lead API Architect

An internationally-known author and lecturer, Mike Amundsen travels throughout the United States and Europe, consulting and speaking on a wide range of topics including distributed network architecture, Web application development and cloud computing. His recent work focuses on the role hypermedia plays in creating and maintaining applications that can successfully evolve over time. He has more than a dozen books to his credit, the most recent of which is RESTful Web APIs.

Related Articles


Applying and Extending DHARMA

This post gives some practical examples of the DHARMA method for API Security in a Microservice Architecture, and also shares some opportunities for extending the model.

Matt McLarty on Jul 9, 2018

Microservices and APIs
API Strategy

Microservices, APIs and Innovation: The Power of APIs

Explore the role APIs play in empowering teams and enabling organizations to innovate.

Mike Amundsen on May 24, 2018

How API Languages Evolve
API Design

How API Languages Evolve

As API systems mature, knowing the history and evolution of various API languages will help organizations create robust and successful landscapes.

Erik Wilde on Oct 17, 2017

Join the Conversation