Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

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

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



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