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.
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.
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.
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.
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.
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.
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.
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.
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.