{"API Evangelist"}

Rolling The Dice - Swagger, Postman, and ALPS

I enjoy playing with simple, meaningful ways of leaning about APIs. The other day, during the regular monitoring of the API space, I came across a simple dice rolling API, which I decide to map out using Swagger. Shortly after I did  this, I saw Mike Amundsen post an ALPS representation of the Dice Rolling API. Around the same time, I then imported my Swagger into my Postman client, and exported a Postman collection.

Once I had the three formats, I sat back to consider what each of these representations mean to me:

  • Swagger - A map of the surface area that is dice rolling.
  • Postman - A single representation of actions that can be taken--now.
  • ALPs - A representations of the what it means to roll the dice.

I am constantly working to evolve how I view the available API formats that are emerging throughout the space. I will be spending more time generating machine readable definitions for APIs in my stack, trying to push these definitions through these valuable filters. I do not think any single approach provides me with a definitive view of the resources I am describing, but at least give me with various lenses to look through, during my journey.

Swagger left me feel like I am mapping out a vast expanse, but alone doesn't do much for me without more tooling to interpret the map. Postman left me feeling like I could do one thing, linked to the surface area I mapped with my Swagger, but was very confined to just that specific instance, within the world I have drawn with Swagger. ALPS left me feeling like I described something meaningful, closer to the actual experience of rolling a dice. 

Ultimately I do not see any of the emerging approaches to defining API driven resources as 100% the solution, or in black and white terms as wrong or right. I see Swagger as very much a bridge to a better defined world, while Postman satisfies the more immediate urges that I have, but ALPS...ALPS has the potential to help me internalize, feel, and interact with my digital resources, in a way that is much closer to the real world (not quite, but closer).

A Cleaner, Simpler Example of API To SPA

One of my areas of research that got boost of energy at Gluecon last week, was the area of Single Page Applications, aka SPAs. SPAs are one huge area of potential growth for the API space, but like many other areas, they haven't seen the wider, more meaningful deployments, or adoption, that I had hoped for early on. I think up until now the definition of what an SPA is has been heavily dominated by the technical side of things, as opposed to the delivery side--SPA are still mostly about providing solutions for developers, over solutions for the end-user or business owner.

When it comes to SPAs, I stay away from the more established frameworks, opting for a simpler design--minimal platform or framework adoption. Not that solutions like Angular and Backbone don't do amazing things, just at this point in my career, I'm looking to avoid the adoption, and resulting dogma and dependency that can often come from drinking a specific frameworks kool-aid. I guess the overall footprint needs to be small, before I will allow something to creep my day to day operational world.

While at Gluecon, I was given a demo of a new product, which i won't go into detail about now, but I feel moves us closer to the vision than I have in my head. Many of the existing SPAs employ APIs, but I envision a world where you can design, deploy, and manage APIs, which alongside you can also deploy and manage simple, useful SPAs driven by your valuable API resources. I keep an eye on the SPA space, so I can be in tune with anything that emerges--hopefully my stories and research will also stimulate other solutions in the space as well.

To help you understand the potential for APIs in the SPA space, I am talking about deploying a simple, and I mean as simple as you can SPA deployment, using an API that is defined using a machine readable API definition like Swagger or API Blueprint. I want to be able to deploy 10s or 100s of mini sites, landing pages, and apps from a single stack of API resources. API providers, and consumers should be able to easily deploy the SPAs they need, driven by the valuable APIs of their choosing, into the infrastructure they desire, like on Github Pages, Heroku, or their own internal infrastructure. 

Some day, we will see the cleaner, simple example of an API to SPA solution, that for now, is trapped in my head. Now that I write about this, I would also think of it as a lightweight, API client, which I'd also like to see be hypermedia compliant--man I am a demanding shit. ;-) 

Why You Are Not Doing Microservices Right!

Yeah, I know, it is a click-bait title. My goal is to not flame the haters, but educate everyone involved, both the people looking to learn about microservices, and those who are practicing microservices, so I'm hoping you will forgive me--my goal is not page views.

I'm sticking to my goal of not making microservices a regular thing I talk about, but I wanted to share some observations after listening to folks talk at Gluecon last week--a week that was full of microservices love (and hate). In the past, I mentioned that I received a handful of emails, and DMS from folks letting me know I'm not doing microservices, and after Gluecon I think I have a beginning list of why I think people generally are telling me I'm doing it wrong.

  • Tooling - People tend to identify with the tooling they use, and deeply associate the function with the tool. So if I don't use Puppet or Chef, I'm not orchestrating. If your not using Jenkins, your not doing continous delivery, and so on. This is dangerous for microservices storytelling, but also is something that will continue.
  • Vendor - This is probably the most egregious reason I see people telling others they are doing microservices wrong, and is somewhat akin to the tooling item, but is really just rooted in selling you something. You will never do it right, unless you are their customer, so don't worry about it.
  • Scope - You just aren't doing it at the scope someone else is doing it. Microservices is something large enterprises do, not small companies, or individuals. You have to be operating across many availability zones, many servers, etc. Horseshit. Microservices can be done at any scope, don't listen to them.
  • Completeness - You are only doing some of the aspects of microservices. Maybe you don't need to orchestrate across many operational zones, and your traffic looks very different than some of the usual suspects. Microservices is very seldom a complete picture, it is more about doing what works for you, cherry picking the valuable items you can apply in your world, not any complete definition.
  • Incomplete Info - Someone just read a single blog post you wrote, and hasn't been following the series, asked any questions, and just make assumptions about a single thing you wrote. While I feel you should make each post as complete as possible, the responsibility is on the reader to do their homework - Bwahahaha! yeah right, pundits will never do that.

So far these are the biggest reasons that I've extracted from people me telling me I am not doing it right. Ultimately it comes down to power and control, which I saw play out with SOA, REST, Linked Data, and other areas of "API". They either want to make you feel small, or not cool because you aren't using the tools they are using, or they just want you to buy their snake oil. 

In the end, for me, microservices are just a new storytelling package. They are mostly marketing, as many of the skeptics like to point out, and the companies who are truly doing microservices, will care about sharing their real-world stories, and work overtime to help you understand--there are a handful of them out there, like Runscope and Iron.io

For me, I will be focusing on the moving parts of microservices, which is why you'll see me talking about API design, deployment, management, testing, monitoring, security over just "microservices" umbrella. I could easily attack many of the pundits who challenge me, and say you aren't doing API management, evangelism, monetization, or other critical areas right, but why would I? Where does that get us?

As usual, if you have any questions, let me know how I can help. I'm happy to share, as I try to make sense of all of this. I'm adding some new research sites to support the conversation. 

The Emphasis During Next Phase Of API Evangelist Will Be About You Telling Your Story

I am going on five years of API Evangelist this summer, and I've been doing some reflecting about what the next five years will be about. While listening to my friend Mike Amundsen (@mamund), I had an idea, that I think I will evolve more during the operations of the next five years of API Evangelist (yes, sorry I'm not going anywhere).

First, I want to clarify that when I started API Evangelist in summer of 2010, I spent a lot of time trying to create a logo, resulting in me creating this temporary (5 years) logo, that you have seen on my t-shirts for the last five years.

After listening to Mike spin his yarn, I'm convinced that the next wave of growth for API Evangelist has very little to do with me, and my brand, than it does with the rest of the API community. I've spent a lot of time sharing stories, but for us to get to the next level, it has to be about the community sharing its stories, or we will never get to the scale all of us API delusionaries envision. 

To support this vision, I'm going to play with a new logo for API Evangelist, and print up a round of t-shirts with this evolution of the logo.

I know I'll get a lot of flack from the restarfarians, and hypermedia folks about the design, but it is more about the storytelling, than it is about being technical, but in my opinion, they both work in concert. I've often answered, when people ask me what is scale for API Evangelist, that it is about having hundreds of people doing what I do, across many business sectors, around the globe--this new design reflects that.

While this is a marketing effort for my brand, it really is about the next phase of growth for the space. To get to that API economy thing we are all showcase across the space, we are going to need API Evangelists to step up and own each sector, region, and country around the globe. API Evangelist isn't something that can scale as a business, it will take people who are passionate to step up in their industries and regions, and help evangelize APIs in a way that isn't about products, but about ideas, stories, and the people and brands who make things go around.

I'll let you know when t-shirts are avaiable, if you'd like to have one let me know, but in exchange you have be the evangelist that is needed in your area--otherwise you will have to wear the regular conference schwag you get at conferences and hackathons. ;-)

Going Beyond Just Documenting Your API, And Making Things Fun

I look at a lot of API documentation, something that until recently has been pretty static--pun intended. As an API consumer I really appreciate standardized approaches to documenting an API, like using Swagger or API Blueprint, but I also really enjoy when people go the extra mile to add little details, that make the experience a little more fun.

A recent example of this is from the Spotify API team. When it comes to the search endpoint for the Spotify API, they put in this little addition:

The field filter tag:new can be used in album searches to retrieve only albums released in the last two weeks. The field filter tag:hipster can be used in album searches to retrieve only albums with the lowest 10% popularity.

I love shit like this. It makes the often mundane world of APIs, a lttle more bright. It shows that there is a human beneath the very technical story that is often being told as part of API operatoins. 

I don't about you, while I enjoy the self-service nature of APIs, where I don't have to deal with people and sales teams to be able to put a valuable resource to usee--I also enoy knowing there is a human behind the scenes. Especially if it someone who cares enough about an API enough to have fun, and enjoy themselves along the way.

Swagger Allows You To See The Girl In The Red Dress

While at Gluecon this week, one of the events I particpated in was the Swagger API Meetup, Tuesday evening. There was a small group of Colorado Bros (TM) there, admittedly there "just for the beers", who asked what is Swagger? Valid question, and something I'm always willing to help onboard folks with. First I made sure they knew what an API was, then simply stated, "Swagger lets you see the girl in the red dress" -- making a Matrix reference, hoping to onboard them with the concept of Swagger, via a familiar movie analogy. 

As I've spent time hand crafting the Swagger definitions for my 25 APIs, which includes almost 350 endpoints, the surface area of my operations have slowly come into focus. Before this, the only visual assistance I had was via any client UI I crafted on top of my APIs. My APIs are so much more than just the single client I had built for them, but this was the reality I had constructed. Swagger allows me to see my API, beyond just the 0s and 1s flying by on my screen, giving me a reference that helps not just see my own APIs, but also potentially share with others, and have a conversation around what is possible with my APIs.

I'll keep working on this Matrix analogy to help people understand what Swagger is. If nothing else it will just open up a deeper conversation about what APis are, and the Swagger brings to the table. The ironic thing about this, and I know that my friend Mike Amundsen (@mamund) will agree, is that the girl in the red dress doesn't exist, and in fact API definitons are just a mental crutch, assisting us down a longer road, towards a deeper understanding of how we define our digital self, and the increasingly digital world we live in--I apologize, I get ahead of myself, let me keep with the stories at hand, and not give away future sequels.

A Unique and Personal API Onboarding Experience

I have written many times before about the right way to onboard with an API, as well as how not to onboard with an API. I see a lot of APIs, and can tell you which APIs have put thought into the process, and those who haven't. Helping companies smooth out the sharp edges on their API onboarding is something I spend a lot of time doing, so I work hard to make sure the topic shows up regularly in my writing.

Today I want to highlight a slight different onboarding email I received from Weather2020:

Hi there Mr. Lane!

First off I'll get my lil bit of gushing out of the way.  I really enjoy what you're doing out there in the world.  I love your commitment and passion to the growing world and need for APIs and your focus on the narrative vs. straight technical details.  So even if you find some reason to hate what we have going on here just please keep up the great work.

But now without further delay, I generated a key that grants you an unlimited number of calls.  That key is: c47c5e6e52ae4ae9183e65f30390693f3ee

The structure of our API calls are:http://api.weather2020.com/[APIKEY]/[LAT],[LNG]

So a sample functioning call for us here in Kansas City is:http://api.weather2020.com/c47c5e6e52ae4ae9183e65f30390693f3ee/39.099727,-94.578567

Just because you're obviously just a bit of an enthusiast I'll let you know I have 2 other call structures that deliver the forecast data based on zip codes and city names.  I use them strictly for our internal purposes but I've enabled your API key to work with them as well.  Just in case you want to play around with them.  They're not that super impressive but involved a very different kind of internal data mapping so I'm mildly proud of em.http://api.weather2020.com/zip/c47c5e6e52ae4ae9183e65f30390693f3ee/90210http://api.weather2020.com/city/c47c5e6e52ae4ae9183e65f30390693f3ee/Portland,OR

I plan to have some documentation at the root API domain very soon ( ie. here: http://api.weather2020.com ) .  So hopefully none of the returned data is too much of a mystery.  If you have any questions just let me know.  Also if you have any feedback whatsoever I'd love to hear it.  I can always use some wisdom!


I do not always read the API signup emails I receive, but I do store them in a folder for later review, and I happen to read this one today. It always makes me happy to receive nice emails from my readers, but the fact that this was also in the form of an API onboarding response--made me smile.

I added a couple random characters to the API key above, so don't worry about the security side of this post. I don't expect everyone to personalize their new developers message like this, but I do think it is helpful to let developers know there is a human behind the self-service registration for any API--it could go a long way.

Usage Of Swagger For The APIs At The UC Santa Barbara Lab for Research on Adaptive Computing Environments

This is a Github issue submission I received, in response to whether or not anyone is doing anything interesting with Swagger. In the lead up to talks about Swagger next week at Gluecon, in Colorado. I'm pretty impressed with this work at UCSB, and while I am processing it, I wanted to share with you, and hopefully stimulate others to share what they are working on behind the scenes, using Swagger--I've gotten some pretty cool submissions so far.

We use Swagger in a series of on going research projects at the RACELab of UC Santa Barbara. Our research focuses on designing and implementing new mechanisms for governing APIs in cloud platforms. Following are some of our published works that make use of Swagger.

In first two papers, we use Swagger as a mechanism for describing the syntax and semantics of web APIs. The base Swagger standard covers all the crucial syntactic features of the APIs. We extended the base Swagger specification to include some simple axiomatic semantics (API preconditions and postconditions). We use this syntactic and semantic information to measure the similarity between different API alternatives.

In EAGER (Enforced API Governance Engine for REST), we use the base Swagger 1.1 standard to describe all APIs deployed into the cloud. We auto-generate Swagger descriptions from Java (JAXRS) source code at the compile-time using a custom Maven plug-in. Once uploaded to the cloud, we use Swagger descriptions to validate APIs, enforce policies on them and establish the backward compatibility between different versions of the same API. This way we can prevent or warn the API developer when a backward incompatible API change is being rolled out into a production cloud.

Are You Doing Anything Interesting With @APIBlueprint? Or Know Someone Who Is?

I am preparing for a big week of discussion around API definitions at Gluecon, and in addition to working on my Swagger research, I kicked off deeper research into API Blueprin, looking for the companies that are doing interesting things in the space, using the machine readable API definition format.

As i do with all my work, I have a Github repository setup for the research, allowing me to publish all of my work publicly, and manage feedback and engagement with the community, using my Github workflow. If you want to make any changes to the data you can fork and submit a pull request, or you can also suggest companies I should be looking at, as a Github issue.

So far, I've broken things into four areas:

  • Platform Integrations - Companies who are using the API Blueprint specification as part of their platforms--essentially baking it in.
  • External Integrations - Companies and individuals who have integrated API Blueprint into an existing platform, or framework, from the oustide-in.
  • Apiary - API providers who are using Apiary as part of their API operations, providing interactive documentation to their consumers.
  • Building Blocks - Some of the common patterns I'm tracking on, regarding how API Blueprint is being applied. 
  • Tooling - What toolin ghas emerged that puts API Blueprint to work, from documentation, to generating code samples, to IDE integration.

I'm working on organizing the tooling that I have found so far, but I figured I'd publish what I have currently, and ask for suggestions about anything that is missing. If you know of a platform that is using API Blueprint, either baked directly in, via an external framework, or are just using Apiary for its documentation, and management platform -- please let me know, by submitting a Github issue.

I know there is a lot more API Blueprint out there, and if you are doing something cool with the API Blueprint specification, there is a good opportunity for it to be included in the discussion next week. If you don't share your story, nobody will know, and there are a huge amount of fence sitters right now when it comes to API definitions--people just waiting, and watching for the right sign to jump in.

I'm going to be writing a lot about API definition formats this week, priming my brain for the conversation at Gluecon next week in Colorado. I apologize in advance. ;-) And thanks for sharing your stories!

It Will Be A Busy Week For API Industry Next Week At Gluecon

I am preparing to head to Colorado next week for Gluecon--one of my can't miss events in the API space. Gluecon is always a great place to be, to discuss the API space with the folks who are leading the charge, but this year is shaping up to be a particularly important one. There are number of things happening this year, primarily focused around API definitions, that stand to have a pretty significant impact on how the space operates.

To help showcase the goings on next week, I wanted to walk through my schedule, which I think speaks for itself. Starting next Tuesday, May 19th, we have two events:

Then on the afternoon of Wednesday May 20th, I am moderating the API session track on the main stage:

  • 1:30-1:45 - Track introduction, Kin Lane (@kinlane)
  • 1:45-2:15 - API Readiness: Visualizing and Virtualizing -- Lorinda Brandon (@lindybrandon), SmartBear
  • 2:15-2:45 - How REST APIs Can Glue All Types of Devices Together -- Jerome Louvel, (@jlouvel) Restlet
  • 2:45-3:15 - Roll-your-own API management platform with nginx and Lua -- Jon Moore(@jon_moore), Comcast
  • 3:15-3:30 - Discussion (with audience) led by Kin Lane (@kinlane)
  • 3:45-4:15 - Building a Node.js API with Swagger -- Jeremy Whitlock (@whitlockjc)
  • 4:15-4:45 - Architectural Patterns for Scaling Microservices and APIs -- Lori MacVittie (@lmacvittie), F5 Networks
  • 4:45-5:00 - Track conclusion by Kin Lane (@kinlane)

Then after the session I am doing a keynote on the main stage on the Tech, Business, and Politics of APIs in 2015, where I'll conclude the latest talk I've been doing around where I see the space going, rooted in stories out of the evolution of my own infrastructure. I first gave the talk at 3Scale in Barcelona, continued to evolve for the audience at APIDays Mediterranea, and will conclude with a version of it at Gluecon.

Many of the core people who are working on the Swagger definition will be present at Gluecon, and while much of the conversation will also be about the wider API space, and other API definition formats, there will be some important discussion about the future of Swagger, and what is next for the open API definition format. In addition to the in-person discussion throughout the week, there will be an virtual gathering of the Swagger working group at the end of the week as well.

Another part of the discussion next week will also be around the API definition format APIs.json, which since we launched the format last year at Gluecon, it make sense to talk about next steps, and some significant additions to the platform that has occurred in recent weeks. APIs.json, bundled with the potential of leading formats like API Blueprint, and Swagger, are delivering a growing number of services, and tooling to almost every step of the API lifecycle in 2015--Gluecon is where we get together to discuss.

If your are applying API definitions to your API lifecycle currently, I strongly urge you to get to Colorado next week for the discussions. I know it is a week away, but getting to Colorado is pretty easy, and this is a conversation you will not want to miss. As usual Gluecon is proving to be where some of the most important conversations occur, in the halls of the Omni Interlocken, and on the stools in the Taproom--we will see you there.