I have a vision of an API notebook in my head I desperately want to get out. First of all, I want to come up with another name for it, which is a journey that always starts with playing around with synonyms. Direct synonyms of notebook include a diary, journal, log, workbook, pad, and binder-yes, all of that is relevant to what I would like to see. After that, a few other words resonated, including album, collection, portfolio, and registry.
This isn't just a folder to put my API definitions. It will be the place where I go to find all the definitions of 3rd party API which IÂ depend on, as well as the APIs I'm designing, deploying, and operating as part of my own business. I want to be able to just record ideas, sketches, and thoughts I have as I'm thinking about APIs. I want to be able to annotate APIs that I find, and iterate, remix, and riff off of other API designers and architects work. Maybe an API sketchbook?
An artistic design book is just the beginning. I'd also like it to be my professional sketchbook, where my business partners and customers can discover the API I depend on, and share with the world. I want it to be a directory of APIs that are relevant to my business. My sketchbook is where I'm creative, but it is also where I get business done. Maybe acting as an API portfolio? I want it to be fun, but also accommodate my professional existence as well.Â
I just want a place where I can design and evolve the API definitions that impact my world. I want to be able to share them, as well as subscribe to other people's API designs. I want my designs versioned, and be able to play back their evolution, and see a timeline, and possibly the attributions of where I found my API inspiration, or leveraged an existing definition or specification. My API sketchbook / folio should evolve with me, and help me make sense of all the API definitions I use, discovery new ones, and always help me not reinvent the wheel.Â
Crafting my dream API sketchbook / portfolio is easier to write about than it will be to build. Doing it simply and beautifully will be hard. Doing it so it scales, and allows me to manage not just 10s or 100s of APIs, but work from thousands of APIs will be very difficult. I'm hoping it is something that I won't have to build on my own, and is an idea that many will contribute to, helping push forward the converstion around how we craft, store, organize, and collaborate around the APIs that are increasingly playing a central role in our business and personal world.
