Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage Guides InfoQ eMag: Description, Discovery, and Profiles - The Next Level in Web APIs

InfoQ eMag: Description, Discovery, and Profiles - The Next Level in Web APIs


This eMag 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 Zoo-Keeper, 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.

Free download

Contents of the Description, Discovery, and Profiles - The Next Level in Web APIs eMag include:

  • Description, Discovery, and Profiles: A Primer - While the process of implementing Web APIs has become common, the tooling for describing, discovering, and understanding the meaning of the tens of thousands of API-based services has yet to settle into a widely-accepted set of standards. There is still quite a bit of opportunity when it comes to defining and implementing tools around the “meta-level” of APIs.
  • 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 PI. But, if you want to create a good API you need a lot more than that. Designing a good API is hard work and it’s easy to feel overwhelmed when it’s your job to make one.
  • 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. But beyond creating a more easily understood spec, 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 - After a flurry of activity from their open working group, Swagger 2.0 was officially released in September 2014. Our interview took place in March 2015, less than one year from the start of the 2.0 process and right after Reverb announced that the responsibility for leading the future of the Swagger specification would be handed over to Smart-Bear, the Massachusetts-based software tools company.
  • 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 when you are developing a web, or mobile application, or possibly integrating between existing systems, is always a tedious task.
  • Profiles on the Web: An Interview with Erik Wilde - Erik Wilde talks to Mike Amundsen 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 designed and implemented.

About InfoQ eMags

InfoQ eMags are professionally designed, downloadable collections of popular InfoQ content - articles, interviews, presentations, and research - covering the latest software development technologies, trends, and topics.