Article Series: Description, Discovery, and Profiles : The Next Level in Web APIs

Posted by Mike Amundsen on May 29, 2015 |


This series focuses on three key areas of "meta-language" for Web APIs: API Description, API Discovery, and API Profiles. You’ll see articles covering all three of these important trends as well as interviews with some of the key personalities in this fast-moving space. API description languages and utilities have been around since the Interface Description Language (IDL) era of the 1980s and 90s. Now we have formats like Swagger, RAML, and Apiary Blueprint as the most popular in the field of Web APIs. API discovery work — finding an API to meet your needs — is primarily a human-driven search, select, and on-boarding process today. However, enterprise-level tooling such as ZooKeeper, Consul, and etcd are pointing the way toward automating much of that process. Finally, API profiles have emerged from the quiet land of library and information science into the world of APIs for the Web. This is a very new field but a few vendors are already taking a look at the possibility of supporting API Profiles today.



Description, Discovery, and Profiles: A Primer

In the opening article of the series Mike Amundsen takes us on a quick tour of three hot topics in the "meta-language" of APIs: Description, Discovery, and Profiles. We’ll look at several formats, key vendors, and identify the opportunities and challenges in this fast-moving portion of the Web API field.


From Doodles to Delivery : An API Design Process

Having a basic understanding of web based applications is a good foundation for designing a working Web API. But, if you want to create a good API you need a lot more than that. Ronnie Mitra investigates what good design is and how using Profiles along with an iterative process can help us achieve it. He will also outline three important phases of design: sketching, prototyping and implementation as well as the tools that will make your job easier.


The Power of RAML

RAML, or the RESTful API Modeling Language, is a relatively new spec based on the YAML format - making it easily read by both humans and machines. Mike Stowe introduces us to the RAML format, reviews avilable uses and tools, and explains why Uri Sarid -  the creator of RAML - wanted to push beyond our current understandings and create a way to model our APIs before even writing one line of code.


APIs with Swagger : An Interview with Reverb’s Tony Tam

In this engaging interview, Mike Amundsen talks to founder and inventor Tony Tam about the history and the future of one of the most widely-used API Description format today: Swagger.



The APIs.json Discovery Format: Potential Engine in the API Economy

In the fast growing world of APIs and microservices, finding just the right API you need when you are developing a web, mobile application, or possibly an integrating between existing systems, is always a tedious task. In this piece, Kin Lane describes his APIs.json API discovery format which can provide pointers to available documentation, licensing, pricing for exsiting Web APIs.


Profiles on the Web: An Interview with Erik Wilde

Erik Wilde has contributed to a number of IETF and W3C standards publications and is the author of RFC6906 ("The Profile Link Relation Type"). In early April, 2015 Erik agreed to sit 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

As this article’s author, Mark Foster, puts it, "Absent profiles, the API space will be relegated to blindly passing around 'magic strings, fooling ourselves into thinking we are passing reliable semantic information." Here, Foster — one of the editors of the ALPS specification — explains what semantic profiles are and how they can transform the way Web APIs are desgined and implemented.




Series Manager

An internationally known author and lecturer, Mike Amundsen travels throughout the world consulting and speaking on a wide range of topics including distributed network architecture, Web application development, and other subjects. In his role of Director of Architecture for the API Academy, Amundsen heads up the API Architecture and Design Practice in North America. He has authored numerous books and papers on programming over the last 15 years. His most recent book is a collaboration with Leonard Richardson titled "RESTful Web APIs" published in 2013. Mike's 2011 book, “Building Hypermedia APIs with HTML5 and Node”, is an oft-cited reference on building adaptable Web applications.




Rate this Article


Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

General Feedback
Marketing and all content copyright © 2006-2016 C4Media Inc. hosted at Contegix, the best ISP we've ever worked with.
Privacy policy

We notice you're using an ad blocker

We understand why you use ad blockers. However to keep InfoQ free we need your support. InfoQ will not provide your data to third parties without individual opt-in consent. We only work with advertisers relevant to our readers. Please consider whitelisting us.