{"API Evangelist"}

The Month At A Glance, Road Map, Support, And The Recent Posts For Your API Platform

I was playing with Microsoft's API Catalog, a tool to visualize and analyze the API overlap between standards specifications and type systems within browsers, and their footer caught my eye. I am always looking for quality examples of companies doing platform communications and support well, and I think their layout, and available building blocks in their footer, is worthy of showcasing.

For me, these numbers, and the available communication and support building blocks, send the right signals--that a platform is alive and active. These are the data points I tune into, to understand how well a platform is doing, or not doing. There are no absolutes when it comes to this type of monitoring, as anything can be gamed, but sign Github activity, road map evolution, and blog storytelling can provide a vital heartbeat for any healthy API platform. 

See The Full Blog Post


What Are The Most Relevant API Topics To Discuss At @APIStrat in Boston This Fall?

We are picking up speed with the planning for @APIStrat in Boston this November, and with the event committee assembled, and the call for talks open, we are looking at what the possible topics are for sessions. We have seeded the list with the usual suspects like API design, management, testing, monitoring, and others, but we want to also consider what the alternative topics are, and what is relevant to the API sector in 2016. 

What is most important to you in 2016? Is it the trendier topics like bots, voice, and IoT? Is it more practical things like evangelism, versioning, and discovery? Is it the technical, business, or politics of APIs that are impacting your operations most in 2016? If you want to come and present on it, make sure you submit your talk by May 20th. Otherwise you are welcome to tweet at us, email at us, write a blog post, commit to a Github repo, or any other way you desire--we'll add into the mix, for the event committee to review.

It is a lot of work to make sure @APIStrat keeps reflecting the wider API movement after 3 years, and we depend on you keeping us informed. I'm enjoying the fact that we are only doing one event this year, as it is giving us more lead time to engage in discussions with the community, and continue making it an inclusive event. Another thing I'd like to hear about from y'all, is what is relevant to Boston, something I'm sure I will learn more about as I continue my profiling of Boston area businesses. 

Let me know your thoughts please!

See The Full Blog Post


More Patents Turning APIs Into An Invasive, Royalty Generating Virus

The relationship between API provider and consumer is a fragile one. As an API provider I am offering up my valuable digital asset, data, content, and digital resources. I would like you to take this Application Programming Interface or SDK that I have built, and put it in your business systems and applications. As an API consumer, I'm given access to valuable business API asset, which I'm expected use in a respectful way, that is always in alignment with a providers terms of service -- an environment where so much can go wrong, and does each day.

I watch companies take a wide range of tones when it comes to setting the stage for this relationship. Some companies are super protective of their valuable content (like Marvel Comics), some are very communicative and inviting like Slack (inject your bot into us). where others wobble between a more open, the back to strict, like Twitter has done over the last couple years. In my opinion, it comes down to how you see your digital resources, and your belief in intellectual property -- when I you, I mean you and your investors.

I try NOT to read all the patent notifications that come into my reader, as it fucking depresses me, but everyone once in a while I have to revisit to help remind everyone, what an illness patents will be, when it comes to APIs working. This fragile relationship I speak of above, operates well, or not very well, depending on how loose, or how much friction exists at this layer. There are plenty of examples out there of APIs who do not do well when they restrict, or too heavily meter API consumers. 

To help build an image in your mind. Imagine the Twitter API, and all the apps that have been built on it. OK, now add in Stripe for payments, Dropbox for storage, Instagram for Images, Facebook for Social, Amazon EC2 for compute, and YouTube for videos. Now, think about enforcing copyright on every API design, and patent licensing on each process involved. It will grind these billion dollar revenue engines to a screeching halt. Nobody will build on these platforms if they have to bake your legal heavy design, and process into their business.

Modern web APIs are balance between the technical, business, and politics of how data, content, and algorithms are exchanged. Simple, ubiquitous web technology is working on the technical side of things. Simple, pay as you go, utility based, and tiered access is helping strike balance on the business side of things. TOS, privacy, security, transparency are the knobs and dials of the political side of things, let's not willingly invite in something so invasive, like patents into the API layer. Patent your algorithm, copyright your content, and license your data, but keep the API definition copyright free, and your API process patent free.

In the "secure cloud storage distribution and aggregation" patent I'm reading this morning, its not the patent that offends me. It is the patent being so focused on the API being the thing that makes the patent. Patent how you index, search, and secure your file storage wizardry, but the API design, and operations should NOT be a focal point of your patent. You want people to integrate with your "secure cloud storage distribution and aggregation", bake the API design and process into their businesses, you want the cloud storage industry to speak your API -- don't lock it down, otherwise API consumers will look elsewhere.

See The Full Blog Post


A Regular Reminder That Storytelling Is The Most Important Tool In Your API Toolbox

I was reminded by my friend Mike Amundsen of the importance of storytelling in our world. When I am asked by anyone doing APIs, what is the most important thing they should be doing, my answer is always "storytelling". I don't care if its internally, publicly, on the corporate blog, or your personal blog, tell the story of what you are doing. I do not care how good your API is, if you aren't telling the story of this, nobody is going to care. 

When I hold up storytelling as the most important tool in your toolbox within developer groups, they often snicker, dismissing it. I also have a contingent of my NOT fanbase in the API space who love to dismiss me with -- nobody reads or cares about stories! I'm never phased by these folks, my focus is on the people who are truly trying to build community, and reach their intended audience. #NoHaterz

While stories swirl all around is many forms, the one I like to reference the most, is when it comes to the mating ritual that is startup funding. If you are looking to get funding for your startup, you have to be sending the right signals, otherwise your VC mate will never be interested in you. You will need to be on TechCrunch, Venture Beat, and other tech blogs. Hacker News, Reddit and Hacker News needs to be in sync. Your stories should also be in sync with what is floating around VC firm blogs, aggregate, and other investor related streams. 

Startup valuations are are defined by an ocean of stories crashing on the shore each day. Bots are a thing because of storytelling. We are focusing on selling to the enterprise and abandoning B2C solutions because of storytelling. Google loves them some moonshot storytelling. Elon Musk understand the importance of the right story at the right time. Stories of what people are using. Stories of what people are investing in. Stories of what the future will hold, and will be a 20B industry by 2020. 

That is marketing Kin! I'd put it in the fiction section of the library if I was in charge, but I'm not. Its all storytelling. If you need another example, visit my secret to Amazon's success post. This story does 2K page views a month, and I've seen it referenced in keynotes, framed on the wall of a bank, and on the home page of a federal agencies internal portal. This story is more fiction than it is fact, yet it keeps on resonating with folks, getting passed around, and turning people on to the concept of APIs, and why they are important.

Please keep telling your story, if for no other reason, so that I have stories to retell. ;-)

See The Full Blog Post


The Wikimedia Unique Devices Data API

I came across the Wikimedia Unique Devices data set, which also is served up as an API endpoint, along with the other APIs the platform offers. The data set and API provides access to a list of unique devices that have visited Wikipedia, for a specific period of time.

The data set and API only has data back to January currently, but I'm sure is something that will evolve over time. I really like the fact that we have organizations who are operating at scale, and are open and willing to share their data. This type of information is high value, and is something that can help us all better understand the ever shifting digital landscape around us--thank you Wikimedia for making accessible.

While playing with their Unique Device API, I also noticed how transparent they are with their page view data, also making it available as simple set of API endpoints. I know Wikimedia is a non-profit, but I can't help but feel their way of doing things provides a blueprint that other commercial platforms should consider following.

See The Full Blog Post


Content That Lives On When You Invest In The Right API Stories, Training, and Guides

I am working with my partner Cloud Elements to build out a community of evangelists, who are interested in delivering on many of the essential building blocks I track on when it comes to API evangelism. I get regular requests from companies who are looking for evangelism and advocacy resources -- in desperate need of smart folks who can help craft content, crank out code, in the service of evangelizing a platform.

The work I'm doing with Cloud Elements, is the early work to help deliver on what API providers, and service providers are needing. Right now we are on-boarding new folks to the concept, and getting feedback on what some of the common elements, and challenges will be. One of the folks I'm engaging with on this is expert PHP and API developer, tech lead, author, consultant and open source maintainer, Lorna Mitchell (@lornajane).

Lorna is one of several folks I've been working with to help deliver on API Evangelist projects ranging from blog, and white papers, to training, and how-to guides. If you are a PHP developer, have been learning about Git and Github in the last couple of years you have probably come across Lorna's work. I was talking to my friend Mark Body on Skype today, and mentioned Lorna and he said oh yeah, I've used her Git training materials before, in my stories and talks -- something I echoed as well, having pointed my readers and clients to her training materials regularly.

After five years of doing what I call hacker storytelling, writing code, JSON, and stories about APIs, I understand how much hard work goes into creating content that is educational and simple, focused on very technical topics like APIs, while also driving search engine traffic over long periods of time. Lorna has done very well these areas,crafting blog posts that will keep being surfaced in Google searches for a long time to come, and help walk people through some very lofty technical concepts--wave after wave.

If you are needing help with storytelling as part of your industry, or API platform, let me know. I'm happy to see where I can help. Feel free to reach out to Lorna as well, she is looking to help the right companies and platforms craft white papers, guides, training and tutorials. If you are an evangelist who is looking to do the same, let me know, and I'm also happy to plug you into the community we are assembling, and see where you can help deliver. If you want to test drive some of first tasks and challenges we have going on in the beta phase, you are welcome to sign up on your own at Mt. EveREST-- things are just getting going, and we could use your feedback.

See The Full Blog Post


API Providers & Consumers Keeping In Touch Is How You Can Set The Right Tone For An API Community

One of the side effects of the recent bot craze, is that I'm getting to showcase the often very healthy API practices of Slack, as they grow, scale, and manage their developer ecosystem. Slack is beginning to renew my faith that there are API providers out there who give a shit, and aren't just looking to exploit their ecosystems. There are two Slack blog posts that have triggered these thoughts, one on the Slack platform road map, and a little thing about release notes, both of which reflect what I would love to see other API providers emulate in their platform operations.

Slack is going the extra mile to set the right tone in their community, with what I consider to be some of the essential communication building blocks of API operations, but they simply call "keep in touch":

  • Recent updates We improve the Slack platform every day by releasing new features, squashing bugs, and delivering fresh documentation. Here's an account of what's recently happened.
  • Support and Discussion - Whether you're working on an app for our App Directory or a custom integration for your team, you'll find yourself in good company, from all of us here at Slack and the wide community of developers working with the platform.
  • @SlackAPI - Slack tweets, news, features and tips can be found at  but this? This is all API, all the time.
  • Platform Blog - A Medium blog dedicated to the Slack API platform.
  • Slack Engineering Blog - A Medium blog dedicated to the Slack engineering team.
  • Platform Roadmap - Come, transform teams, and build the future of work with us--About our road mapExplore our roadmapReview recent platform updates, and Discover what teams want.
  • Register As a Developer - Working with the Slack API? Tell us a bit about yourself! We'll use the answers you supply here to notify you of updates to the Slack API, general Slack API news, and to get a better sense of the variety of developers building into Slack. 

I just copied and pasted that from their developer portal. Slack does not stop there, also providing an FAQ, a Code of Conduct, and Ideaboard to further set the tone for how things can and should work in a community. What I like about the tone Slack is taking, is that it is balanced--"keep in touch"! Which really is just as much about us API consumers, as it is about Slack. Slack has done the hard work of providing most of the essential API building blocks, as well as a valuable API resource, now its up to the community to deliver--this balance is important, and we should be staying in touch.

Remember the tone Twitter took with us? Developer Rules of the Road!! Very different tone than "keep in touch". The tone really matters, as well as the investment in the common building blocks that enable "keeping in touch", both synchronous, and asynchronously. Having a road map, and change log for your API goes a long way, but telling the behind the why, how, and vision behind your road map and change log--gives me hope that this API thing might actually work. 

See The Full Blog Post


Vital Resources Like The Court Listener API Depend On Our Donations To Operate

Despite popular belief in Silicon Valley, there are many different ways to fund the design, development, deployment, and operation of valuable API resources. Not all APIs are destined to be the next Amazon, Twitter, or even Twilio. Some APIs just need exist, be available, and will never be a revenue engine--one of these APIs is the Court Listener API.

Version 3.0 of the Court Listener API possesses 15 valuable endpoints, providing access to courts, dockets, opinions, people, sources, ratings, and other details about how laws are made in the United States. With their latest release containing a comprehensive database of judges and the judiciary, to be linked to Court Listener’s corpus of legal opinions authored by those judges.

Increasingly APIs like Court Listener, and the Human Services Data Specification (HSDS) API, are capturing my attention. These types of APIs represent the type of impact I'm looking to make using APIs, going beyond what APIs can do for a single application or industry, but what they can do for wider sections of our society. Focusing on getting agile, nimble, and more efficient in how craft laws in our country, and how we make sure people are fed, and find the government services they need in their life.

The Court Listener API depends on grants, and donations to operate, which is an approach I will be showcasing more when it applies to APIs that deliver valuable human, civic, and research related resources. APIs like the Court Listener API provide an important window into how our local, state, and federal judicial system is operating (or not), and will need our financial support to do what they do. Which I think is a very viable approach to designing, deploying, and operating APis -- that is, if we all step up and support these efforts.

See The Full Blog Post


Slack Meets The Minimum Viable API Platform Requirements

I am using my minimum viable API operations definition tool to continue profiling the API sector, this time to size up the Slack API community. Slack is kind of a darling of the API space, so it kind of seem silly to profile them, but profiling those who are doing this API think right, is what API Evangelist all about--whether I follow the hype or not.

Using my minimum viable API definition, I went through the Slack API portal looking for what I'd consider to be the essential building blocks that any modern API platform should have.

API Overview
Name: Slack API
Description: All of our APIs can be used alone or in conjunction with each other to build many different kinds of Slack apps. Whether you're looking to build an official Slack app for your service, or you just want to build a custom integration for your team, we can help you get started!
Image: https://a.slack-edge.com/ae57/img/slack_api_logo.png
API URL(s)
API Portal: https://api.slack.com/
API Base URL: https://slack.com/api/
Onboarding
Getting Started: https://api.slack.com/slack-apps
Registration: https://slackhq.typeform.com/to/kOHQvo
Documentation: https://api.slack.com/rtm
Code: https://api.slack.com/community
Operations
Road Map: https://api.slack.com/roadmap
Change Log: https://api.slack.com/changelog
Pricing: You should be at least sharing some rate limits, acceptable uses, and other pricing and access related information.
Terms of Service: https://slack.com/terms-of-service/api
Definitions
OpenAPI Spec: A machine readable OpenAPI Specification for an API is fast becoming an essential element of API operations.
API Blueprint: A machine readable API Blueprint for an API is fast becoming an essential element of API operations.
Postman Collection: A machine readable Postman Colelction for an API is fast becoming an essential element of API operations.
Communications
Github Org / User: https://github.com/slackhq
Twitter Account: https://twitter.com/slackapi
Blog: https://medium.com/slack-developer-blog
Blog RSS: https://medium.com/feed/slack-developer-blog
Support Page: https://api.slack.com/docs/support
Contact Info
Contact Name: Slack
Contact Email: https://apievangelists.slack.com/help/requests/new

Performing better than the review of the i.Materialise 3D printing API that I conducted the other day, Slack checks off all but one of the essential building blocks-everything except for pricing. The only other area(s) that I find deficient, is when it comes to machine readable API definitions like OpenAPI Spec and Postman Collections. These aren't required for success, but they can sure go a long ways in helping developers on-board from documentation, to generating code, and tooling that will be needed for integration. 

I'm assuming Slack hasn't generated OpenAPI Specs because they have a more XML-RPC design, which I think many folks assume can't be documented in this way. While it doesn't lend itself to more easily being documented with OpenAPI Spec, I found some simple little hacks that make it doable, allowing you to also document even XML-RPC designs. Having some OpenAPI Specs and Postman Collections would make the API more accessible for people looking to play with.

Anyways, I just wanted to test out the minimum viable API operations tool on another API. I am trying to profile several APIs in this way each week, helping the number of APIs I am monitoring grow, while also encouraging other API providers to follow Slack's lead.

See The Full Blog Post


OpenAPI Specifications For 642 Of The Schema.org Types

I am gearing up for another wave of API definition work, so I am taking the opportunity to produce some more tooling that assists me in the process. One of the tools I want to build, is a simple solution for walking me through one or many OpenAPI Specs, and push me to make sure every parameter has a complete set of descriptions. I possess amazing powers of bullshit, and can craft default description for almost anything I come across, but it would be nice to have an an ever evolving autocomplete dictionary to augment my existing super powers. 

I already have an APIs.json driven autocomplete tool, that loops through all the parameters within the OpenAPI Specs that are indexed. I just needed a rich set of fields and parameters to pull from -- Schema.org. The rich vocabulary that is Schema.org possesses 992 properties across 642 schema types. I've long wanted to craft OpenAPI Specs for Schema.org, but needed a reason to help push things forward, and this is a perfect opportunity to kick things off.

As a starting point, I created 642 separate OpenAPI Specs. One for each of the schema types. I already have an API that will generate an OpenAPI Spec from any JSON schema, building out GET, POST, PUT, and DELETE methods, as well as a default 200 response, and connecting it to the schema for the API response definition. As I was doing the work I realized that I didn't want to limit the OpenAPI Specs to just the JSON version, so as I generated I also published a YAML version.

Next I'm going to use these 642 OpenAPI Specs as an autocomplete index for helping me quickly fluff up the parameters of other existing API definitions. Next I'll work on wiring up the hierarchies and relationships present in the Schema.org definitions. Right now, none of the OpenAPI Specs will validate as the parameter types aren't all valid, but I didn't want to lose the object references. 

Beyond being an autocomplete index which I can use across my micro tools for working with API definitions, I am thinking this Schema.org work will bear a shit ton of fruit in future work. I would like to have API implementations for many of the more common Schema.org types, allowing me to help folks design, and deploy Schema.org compliant APIs. Something that I feel will go a long way to help stabilize and standardize APIs, by helping them speak using a more common vocabulary.

See The Full Blog Post


Using My APIs.json Annotation Tool To Drive An API Design Conversation Via Github Issues

I am working on one possible API definition for the Human Services Definition Specification (HSDS), and the next phase of this work involves bringing in a small group of technical, and non-technical folks to have discussions around their API designs, in context of the master specification I am looking to pull together. 

To help drive the discussion I am wanted to use the OpenAPI Specification that I created for HSDS, and I also knew I wanted to use Github issue management to help keep track of the synchronous, and asynchronous conversation that would occur around it. However Github tends to have a perceived barrier to entry for many non-developers (which I don't fully get), so I wanted to leverage the platform, but also soften the way everyone discussed the overall specification, as well as each individual endpoint.

The HSDS specification is pretty verbose, and I needed a way to have conversations at the high level, but also down to the endpoint level. To help facilitate this, I got to work on a prototype micro tool which enables a conversation around any API(s) that are indexed within an APIs.json file, producing a human readable list of endpoints, parameters, etc., but then uses Github issue management as the core of the conversation. 

Resulting in my APIs.json Annotation tool. It is just a first draft, so there will be a lot of changes that need to occur. I'm going to test it against 20+ APIs.json collections I have defined as part of my API Stack work to try and harden it a little bit. My APIs.json Annotation tool runs in my single repo app style, leveraging Jekyll + Github Pages + Github API to operate--Github is the front and backend.

Anyone can view the conversation, but if you want to participate you have to be added to the Github repository, and pass in a Github personal token. This is something I often automate with a simple Github login, where I use OAuth.io to obtain token, but I kind of see the token as a minimum viable investment to understanding Github for using each tool.

It is really important to me that each app stands on its own feet. Not all of my micro tools that I develop in this way will enjoy zero outside dependencies, but most of them can be easily forked, and ran in any Github user account or org (with little or no setup). Conversations around API is just one area I am looking to simulate with this approach to delivering tooling, and specifically APIs.json tooling, that can be used throughout an API life cycle. 

You are welcome to play with the APIs.json Annotation, or any of the other tools I have listed on my home page. I will keep adding them here, so that they can be found, but like all my work they are all a work in progress. Each tool has its own dedicated repo and issue management, where you are welcome to join in the conversation around the road map for each one. I am just looking to develop a robust toolbox of small micro tools that will help be more successful across the life cycle of the APIs I am working on, but maybe you can benefit using them too.

See The Full Blog Post


I Like Working With JSON On Github Because CORS Is Never An Issue

I tend to only work in environments where I have full control over the server, so Cross-origin resource sharing (CORS) is never really an issue for any of the APIs I have control over, but is a pervasive problem for APIs, and JSON files I come across on the web. This is one of the reasons I really enjoy the fact that I publish all of my JSON driven, hacker storytelling projects using Github Pages and Jekyll.

In the last couple weeks I have been working on a bunch of micro tools that deliver specific functionality which can then be used throughout the API life cycle. All of these apps are developed using JavaScript, and depend on being able to read from any number of JSON file stores. Sometimes these files are stored within the project, but most likely I'm calling the remote JSON files of other projects, something that depends on the sharing of resources across domains.

If I am publishing a JSON file publicly on the open Internet, I want it to be accessible from anywhere. CORS has to be default. The speed, and agility at which I'm able to ingest and work with APIs.json files, and the OpenAPI Spec indexes they contain, sets me up for some serious nimbleness across my work.

If you are working with open data on the web, make sure and consider the CORS enablement by default when working with your JSON data on Github. It will make your life easier, as well as anyone else who will be looking to consume the valuable data you are putting out there.

See The Full Blog Post


I Am Working With @HitchHQ Team To Help API Providers Build Their Communities

I'm always on the hunt for like-minded folks who I can partner with, and bring needed products, services, and tools to the API space. If someone is selling something to the API space, its likely I have had a conversation with them about the sector at some point. I always enjoy these regular encounters, but its the handful of them that continue, and evolve into deeper relationships that I enjoy the most.

One of most recent relationship which I have been cultivating, is with a new API startup called Hitch. I have a long history with both the founders Bruno Pedro (@bpedro) and Luke Miller (@lukeam), in their previous lives with API Changelog and 3Scale, but began talking with them more heavily bout their vision for Hitch earlier this year. I have spent considerable time with Luke and Bruno discussing the current state of the API life cycle, from design to deprecation, helping contribute to their vision and road map in any way that I can.

As Hitch prepares to shift into higher gear, helping API providers build community, the Hitch team asked me to join the team in an advisory capacity. I am always happy to share my thoughts, experience, and views on the space, but I'm stoked for the opportunity to help advise them on their road map. As Hitch evolves, you'll hear me tell more stories about the solutions they are bringing to the API life cycle. I'm hoping I can influence what they bring to the API life cycle, while also using them as another valuable source of stories about the API space. 

Hitch is just getting going so there isn't much for me to focus on yet, but I'm looking forward to continue sharing my research with the team, to help them in any way I can. I just wanted to put it out there that I was involved, and turn up the volume my public storytelling about building community, and the API life cycle in preparation for what Hitch is bringing to table. I'm looking forward to being part of what is cooking over at Hitch--stay tuned!

See The Full Blog Post


Helping Folks Leave Their Platform and Language Baggage At Home Using API Definition Formats

I was just participating in an interesting conference call about multiple API implementations, which are putting the Human Services Definition Specification (HSDS) to use. The call was brought together discuss a shift in the current path one of the projects was taking, which involved using Azure Search Service, and whether or not the original vendor solution was still necessary, because the cloud solution appeared to meet all their needs.

I sat and listened to the pros and cons of each approach. Why Azure allowed them to quickly meet the project needs, and could scale. Why the other vendor solution had a more holistic view of the problem, and shared the investment from many implementations. I had nothing to offer. The only common ground I had was around the already established schema for delivering human services. I didn't have any awareness of each individual project, the resources and skills available each group possessed, or a belief in any particular cloud platform, database solution, or programming language.

While Azure, and the other vendor approach dominated the first part of the conversation, everyone one on the call was in agreement around HSDS driving everyone's schema, while also agreeing were missing a common approach to defining and delivering the API. The vendor on the call was working on the next version of their API which used the HSDS format, with the Azure driven solution spoke HSDS as well. To add to the mix, I am also working on two additional implementations that will also be speaking HSDS--we all just needed a common approach to defining the API.

As the next step, I suggested scheduling another call, where I walk through the API definition I am applying to my projects, providing a YAML version of my OpenAPI Spec definition. I prefer using YAML, to help lower the cognitive barrier to entry for business users of the group, demonstrating how OpenAPI Spec can be used by everyone to quantify each individual API, but in a way that we can share, discuss, and reuse--helping establish a harmony in design across all of our implementations.

I always work hard to not set the bar to high when it comes to the magical powers of API definitions have when it comes to facilitating API discussions between technical and business groups, but the benefits in situations like this are clear. I feel API definitions have the potential to help folks unpack the dogma (and insecurities) we all possess around the architectural decisions we have made, the programming languages we are using, and the cloud platforms that are increasingly depending on. Continuing to demonstrate for me the ways that APIs can help facilitate how we work together, with API definitions acting as a machine readable specification that can help us define what is needed by everyone at the table.

See The Full Blog Post


Empowering You To Make Informed Decisions Around Your Information Is What The Personal API Is About

My friend Tom Woodward is continuing his personal API journey on his blog, sharing more of his thoughts around taking control over his information, and sharing some of the conversational exhaust that his journey has generated. The conversation around what what is "personal API", is where the value in all of this for me, something that is full of endless perspectives, and views of what APIs do. Which is one of the things I truly love about APIs, as they mean so many different things to different folks.

As i mentioned before, when I mention the concept of personal API to some of my engineering friends, they seem to always focus on people designing, developing, and operating an API stack on their own server, or at home. The recent post from Tom, focuses around a comment from our other friend Alan, who commented on his previous post, talking about the process of personal API being, "a bit binary (reclaim or “let it burn”)". I'm thinking Alan's perspective has been strongly influenced by Tom's heavy "reclaim" desires, as well as two other friends, who have embarked on similar journeys.

I'm endlessly intrigued by the dimensions of personal API that people are drawn into, and focus on. That personal API is about hosting or managing your API, or just about getting your information out of someones platform. When I read Tom's post, I actually do not see local or cloud, reclaim or let it burn, I see Tom working to understanding what information he generates online, understand the tradeoff's around the platform where this information lives, then logically making decisions around how he manage this. Sure this might involve abandoning platforms, and could involve setting up some self-hosted APIs, but more often it will not.

I can't help but think Alan might be missing some details of his own personal API journey, as a result of his focus on his friends. When we focus to heavily on a specific aspect of API enablement (migration), I find people tend to miss many of the other benefits also occurring. I'm guessing that many the reasons that went into his original adoption of Flickr, feeling like he can rely on it, and his lack of interest in ever leaving the platform, were most likely API influenced. APIs have have made Flickr a a ubiquitous tool in our lives, allowing the community to share photos using oEmbed, develop valuable syndication, upload, and other useful solution, including WordPress integrations, and tools like Aperture--APIs have been shaping everyone's decision to use the photo sharing platform for many years. 

One of the reasons I keep using the phrase personal API, is because of how people respond to it, view it, and accept of reject it. To me, personal API involves having my own hosted API stack, depending on 3rd party APIs (my personal storage API is Amazon S3 & Dropbox), to host, sync, share, syndicate, publish, reclaim, orchestrate, collaborate, control, open, and restrict access to my bits and bytes. My journey is not yours, and your journey is not mine, but the process of sharing our stories, and having conversations around it are critical to each of us learning from each other.

APIs are empowering every brand you know and love (or hate) to make decisions around how they maximize where their bits and bytes are stored, accessed, and put to use across the web, mobile, and increasingly devices. Additionally APIs are empowering every brand you know and love (or hate) to also make better decisions around how they maximize where your bits and bytes are stored, accessed, and put to use across the web, mobile, and increasingly devices. Personal APIs are about shifting this balance in your favor, but for many of us, in many situations, we are fine with offloading these decisions to others, as it can be lot of work to operate on our own.  At some point though, when they are ready, there will be a wealth of information out there to help them take back control, no matter how small that first step it might be.

In the end, I don't care if anyone cares about APIs, or personal APIs, but I do care about people being aware of the online services they use, and that they are equipped to make the best possible decisions they can about what services they use. For me it is less about APIs, than it is about how APIs are already being used to enable your world, and helping ensure that you have the awareness and opportunity to assert whatever amount of control over your digital self that you feel comfortable doing, whenever you are ready.

See The Full Blog Post


Sizing Up The i.Materialise 3D Printing API With My Minimum Viable API Operations Definition

I always have an inbox full of requests from companies asking me to take a look at their APIs, and provide any feedback that I can. I do conduct a more formal review for some companies, but I also enjoy looking through the API operations of any API, just as part of my regular monitoring (if I have time). When I do have time, the first part of any scope of review, is to see if it meets my definition of a minimum viable API operation.

This is a definition I've been refining for over five years now, looking through thousands of APIs. Even with all this refinement, I still need a single place I could go, and quickly apply to any of the APIs that are in my review queue. My objective in doing these reviews is partly to help me get to know what an API does, but also provide feedback to the API providers, as well as generate stories that I can share with my readers, helping them polish their own strategy along the way.

To help me streamline the reviews I do, and deliver feedback to API providers, I created a little micro tool for my self, that I can use as a checklist while I go through the operations of each API in my queue. To beta test my minimum viable API operation definition tool, I profiled the 3D printing API i.Materialise.

API Overview
Name: i.materialise
Description: i.materialise has developed several interfaces (APIs) that allows your business to connect with our systems. Integrating apps or websites with i.materialise has never been easier. Feed your data to us, receive all possible order information and let our +100 3D printers do the rest!
Image: https://i.materialise.com/img/API/imat-logo-white.png
API URL(s)
API Portal: https://i.materialise.com/api
API Base URL: https://i.materialise.com/web-api/
Onboarding
Getting Started: https://i.materialise.com/api/getting-started
Registration: https://imatsandbox.materialise.net/Account/Login
Documentation: http://i.materialise.com/api/docs
Code: Code samples, libraries, and SDKs help reduce friction when on boarding for API consumers.
Operations
Road Map: A road map shared with the community will keep consumers in sync with platform operations, giving them time to prepare, and possibly provide feedback that can be considered.
Change Log: A publicly available change log shared with the community will keep consumers aware of what has happened, and reduce the resources needed to support.
Pricing: https://i.materialise.com/api/business-models
Terms of Service: https://i.materialise.com/legal/terms
Definitions
OpenAPI Spec: A machine readable OpenAPI Specification for an API is fast becoming an essential element of API operations.
API Blueprint: A machine readable API Blueprint for an API is fast becoming an essential element of API operations.
Postman Collection: A machine readable Postman Collection for an API is fast becoming an essential element of API operations.
Communications
Github Org / User: https://github.com/imaterialise
Twitter Account: https://twitter.com/imaterialise
Blog: https://i.materialise.com/blog/
Blog RSS: http://feeds.feedburner.com/imaterialise
Support Page: Pulling together all your support items into a single, easy to find page can help reduce frustration within your API community. Nobody likes to have to hunt down ways to get support, put it in a single page.
Contact Info
Contact Name: A dedicated person, who can be responsible for an API is a pretty fundamental piece of API operations--don't hide.
Contact Email: A dedicated email address for an API is a pretty fundamental piece of API operations--don't hide.

The only areas the i.Materialise API stumbles for me is having a road map, change log, as well as a dedicated support page, with a contact person and email to reach out to. You can go to the public side of the i.Materialise site and use the contact page, which is linked in the footer of the developer portal, but I strongly recommend having a dedicated support page, and channels that are dedicated to the API community.

The blog, RSS, and Twitter feeds are not dedicated to the API, and are company-wide. This is fine, but at some point I recommend a dedicated blog, RSS, and Twitter accounts for the API. It can be easy to burn out API consumers with too much general information that doesn't apply to them, and there is little overhead involved with deploying a blog, RSS, and Twitter accounts dedicated to the community.

iMaterialise is closer to being a complete API definition, than most APIs that I look at--something that won't take much effort to bring up to speed. The area I do recommend they focus energy on is around the availability of an OpenAPI Spec, API Blueprint, and Postman Collections for the platform. These elements would significantly add to the available documentation for the platform, while also allowing them to easily generate SDKs for the platform using APIMATIC, which is another deficient area for the API (no code page). In addition to better docs and SDKs, these API definitions would allow any developers to quick load up, and begin playing with the API in popular HTTP clients like Postman, and DHC

The lack of an OpenAPI Spec is the most deficient area in my opinion. The availability of a definition, would push the presence of the iMaterialise 3D Printing API beyond the minimum viable API operation definition for me, and into the zone of a robust platform. One that will go along way towards attracting new developers, on boarding them quicker, and helping them go from discovery to successful integration -- which is what this is all about.

Next, if I have the time, I will create an OpenAPI Spec for the platform which will give me more awareness around the actual API design.

See The Full Blog Post


API, RSS, and The Ability To Look At Your Company Through An External Lens

A  huge pet peeve for me is when a company has a blog, but not provide an RSS feed--it really grinds my gears! Although it is something that aggravates me, I understand many of the reasons behind it. People just don't see their blog through an outside lens. They visit other company blogs when they want to read them, usually via a bookmark, or possibly rely on an email digest once a week--they aren't RSS reader users. RSS consumers were always a niche (that almost went mainstream), but is one that has taken a big hit with the closing of Google Reader.

I'm sure most of the companies would immediately turn on an RSS feed if I dropped them an email, but I'd rather write about it, and reach just the cream (my readers) on top of the API space. One of the most important side effects of being on the API journey in my opinion, is that expansion, evolution, and fine tuning of your powers for empathy that will occur along the way. Your API developer portal becomes a front line for conversations with the outside world, where you will carefully(hopefully) share your most precious internal resources, and entertain external views on how they should be exposed and put to use. 

In my experience companies who are able to think outside the corporate firewall, do the best with APIs, with those who are open to culture change in close second--everyone else will falter. I can't help but feel that RSS is a very 101 example of this in action. I want you to read my blog, but because I didn't think beyond what I do, and my peers, when it comes to providing and consuming blogs, having an RSS feed didn't occur to me. If I was an RSS reader user, and the absence of RSS was a pain point, my tune would be different.

You can see this awareness in play over at the risk, audit, finance, and compliance platform Workiva. It is one of the few places I've seen RSS at work in such a useful, and transparent way:

This is a level of RSS, and corporate accessibility that I only dream of. If I had an RSS feed for the press releases, event schedule, and SEC filings for every company I track on, I'd be in heaven. However with Workiva, the dream ends there--their blog doesn't have an RSS feed, or at least one that I can easily find. Which for me demonstrates where the average company invests in, and will develop empathy. It is usually developed around their own pain points in their operation, and within their own industry. Workiva is in the the business of monitoring corporations, and they see the value in having RSS for the signals that matter the most to them--blog, obviously not that important of a signal in this game yet.

I do not expect every company to cater to every need the long tail of what the public will want, nor do I expect all companies to be able to see their company through an external lens right out of the gate, but for me, the existence of RSS is one signal I tune into--similar to the signals having an API, or not having an API sends. I understand that many of my readers see RSS as a pretty insignificant thing, but for me having a blog, but not considering the wider syndication, distribution, and consumption of said blog, contributes to how I view a company's ability to think outside their firewall, and empathize with their customers, the public, and external players like me.

See The Full Blog Post


The Average Person Will Never Care About Their Digital Stuff Enough For Personal APIs To Be A Thing

I've heard the same thing for years--that the average person will never care about their digital stuff enough to ever want to learn about APIs, let alone for the concept of the personal API to ever be a thing. People love to comment, and tweet it at me anytime I talk about evangelizing APIs to normals, about reclaiming your domain, or the concept of the personal API

First off, you aren't original. IT has been telling the normals to not worry their :pretty little head" about the technical details for many, many years. It is how those with the power stay in power. If people are technically literate, and we built simple technology solutions for people, they wouldn't need us, or buy our bullshit. It is a very scary notion for many of us very insecure technologists. 

I've worked as a professional developer since 1987, IT lead since 1998, and been evangelizing the API opportunity since 2004. These arguments are nothing new for me, but it does fascinate me that people think they are original, with very little awareness of the larger machine they operate on behalf of when they wield these statements. Like I should stop doing what I do, and having the expectations that I have, because the entire world will not fall into line -- its all or nothing. ?? WTF

I do not think in scale like you do. You are the slave in believing that all your ideas should scale. Not me. I'm happy if I reach one person. People like Tom Woodward (@twoodwar), who understand that personal APIs are not about a single, perfect stack of APIs, living on a single beautiful server in your living room. Which is another rookie assault I get from fantasy believing developers looking to disarm my notion of the personal API, with their extremely simple view of what it is a "personal API".

Tom is well on his way, when it comes to the API journey. Tom understands that he doesn't have to be a rockstar ninja developer, or all mighty IT player to use APIs. Tom is just working to understand the footprint he leaves online each day, where all hist bits and bytes live, and how he can assert more control over this digital version of his existence. Tom will mostly likely never have a perfect stack of APIs (as technologists envision), but he is making some impressive inroads when it comes to identifying where he operates online, where he'd prefer to be operating, and how APIs can help him achieve the level of understanding and control he is seeking.

My mission as the API Evangelist is not about convincing everyone that APIs are a thing, and that everyone should care about APIs being available on all the platforms that we use as part of personal and professional lives. My mission is about convincing individuals, and individual business owners that they should always be asking the questions that Tom is asking, and working towards a better understanding of their digital self. Each person, business, organization, institution, or government agency I can influence to embark on their API journey, is a win for me.

So remember, when you tell me how nobody will every care about their digital stuff enough to want to learn about APIs, or embark on their own personal API journey, you just marked yourself as being a cog in a very old machine. You believe you are smarter than the average person, and that people are incapable of managing their own digital self, and should pay you, and the new class of technologists to do it for them. I probably shouldn't be educating y'all about this, and just let you keep self identifying for me where you stand on what role technology plays in our lives.

See The Full Blog Post


Competing Views Around The Value And Ownership Of Digital Resources Impacting API Security

I was reading a post about how having an unclear sense of ownership hurts API security, which showcases the different views on who owns security, when it comes to exposing corporate digital assets via APIs. When I read the title, I anticipated the story being about a difference in how ownership of the asset(s) itself is viewed, but it ended up focusing on the ownership of security itself, not ownership of the assets which are being exposed -- something I think gets closer to the root of the problem, than who "owns security". 

In short, the IT and developers who are often charged with exposing corporate assets via APIs will view those digital resource in some very different ways, than other people at the company. These groups will focus on exposing digital resources in a very technical sense, making them available so that others can integrate into their apps and systems--it isn't always in their nature to secure things sensibly. Their focus is to open up access, something the article touches on, but is something I think it goes deeper than just being about API security. Developers and IT are rarely ever going to see the digital resource in the same way that business stakeholders will, let alone security focused players (hopefully your IT and dev team has specialist influencing things).

APIs have made a name for themselves because a handful of companies successfully exposed their digital resources in this new way, allowing external perspectives of those digital resources to enter the conversation, which allowed for innovation to occur. In this handful of API origin stories we tell like to tell, owners of the digital resources at play were open to outside views of what their digital resource was, and how that resource could be put to use. These leading companies were open to an alternative view of the ownership and access of these digital resources, something that allowed API platforms to flourish << This is not something that will happen in all situations.

APIs really begin to go wrong, when the sense of ownership around digital resource is already unhealthy, resulting in what my friend Ed Anuff speaks of, with everyone doing the API economy wrong. Without proper buy-in, developers and IT will often overlook security around resources being exposed--they just don't understand the importance of the resource in the same way. Coming from the opposite direction, business users will often come in and apply their "wet blanket" sense of ownership on the platform--resulting in heavy handed registration and approval flows, sales cycle(s), pricing, rate limits, and other common things you see slow API adoption.

APIs should be about us exposing our digital resources using the now ubiquitous Internet technology, in a way that opens up our resources, and the culture our business, organizations, institutions, and government agencies to outside views about what our resources are, and how they can be put to use. This is something that when done in the right environment, can reap some serious benefits for everyone involved, but when done in a culture where there is a already an imbalance around what digital resource ownership is, shit can really go wrong -- with security being just one stage where it plays out. In the end, APIs are not for everyone. Some people just have too strict of a view around the value of their digital resources, and of the ownership of that resource, for the API thing to every actually work--with company IT and developer security practices being just a symptom of a much larger illness.

See The Full Blog Post


The Pricing & Plans For 250 API Platforms

I track on the API operations of around 2000 companies. Honestly, most of the 10K+ APIs in the ProgrammableWeb API directory have long been gone, deprecated, acquired, and had the lights shut off. There are only a couple thousand companies, institutions, organizations, and government who are doing public APIs, with only a couple hundred doing them in an interesting way.

This should not diminish the API conversation, as public APIs are just one aspect of the API discussion, and honestly it is one are that not all companies and organizations will have the stomach for. However, a certain amount of available public APIs will always play an important role in setting the tone for the entire API space, providing us with a (hopefully a diverse amount of) lead(s) when it comes to crafting our own strategies for operating our businesses on the Internet. Very little of what I do as the API Evangelist involves ideas that originate from my own head, and is something that requires a wealth of examples which I can point to in the wild. 

I am working on new ways to earn a living, while also generating research, analysis, code, and specification that the API sector can put to use in their own operations. One way I will be doing this, is by publishing technology, businesses, and politics of API design guides. This isn't API design as in the sense of REST, and how you craft endpoints, it is design thinking around the operations of your API. I learn a ton, flipping through the API portals of the 2000+ companies I keep an eye on, and I wanted to carve off small chunks of this, and share with you.

One area of API operations that has always fascinated me, and is one of the original founding focuses of API Evangelist, is how companies craft their API plans and pricing. Whether or not an API has a plans & pricing page is a very telling signal all by itself, as APIs are often a side-project, without any real support and investment from its parent company or organization, and the lack of a coherent plan, with simple pricing is often a sign of other deficiencies. However when an API plan and pricing page is present, I to find it to be a very telling representation of a company, organization, institution, government agencies, and even individual(s) in some cases. 

I track on many data points for any single API I keep an eye on. Ranging from their Twitter account, and Blog RSS, to the activity of their Github profiles. One of the areas I link to, when present, is the plans and pricing pages. This gives me the ability to quickly check up on the pricing of APIs across various business sectors, something that drives my API plans research. With the help of my organization API, and my screenshot API, I was able to easily harvest, organize, and make available the plans and pricing for 250 of what I feel are some of the more relevant APIs out there today.

To help make my research more explorable, I organized my API plan and pricing highlights into a single PDF guide, which allows you to experience the best of my API research, without all the clicking and searching I had to do. When I record details about the plans and pricing for an API, I have a rating of 1-3 for what I call API plan coupling, which is how tightly coupled their monetization strategy is to their API. Is the pricing that is present directly applied to API consumption, or is it more for the SaaS or PaaS side of things? While not all of the plans & pricing I include in this research are tightly coupled with the API, they are all from platforms where the API does play a significant role in platform operations. 

I have many of these the common building blocks employed for the API monetization strategy, and for the actual API plan implementations, recorded in a machine readable way, as part of my research. For this guide, I wanted to step back, and look at things through more of a design lens, and less from the technical, business, or even the political side of things. I think the visual of each plan and pricing page says a lot, and doesn't need a bunch of analysis from me to fluff it up. Just flipping through, you get a sense of what looks good, what doesn't, a process that I think will hopefully push forward more consistency across the API space.

There are numerous lessons present in the screenshots in this guide, around which building blocks are required to support API plans and pricing. Things like breaking things up into tiers, providing contact information, mechanisms for receiving a quote, demo, and know that a trial version is available. There are also lessons in how to present large amounts of very complex information, and some lessons in not how to do it, with plenty of evidence of why simple works. Oh, and that you should have a decent graphic designer! ;-)

I dismiss claims from the vocal startup, and VC elite, who point out the absolutes when it comes to API monetization, and pricing. That freemium won't work, and that offering unlimited access via API is always a mistake. Every company, API, and consumer will be different. In my opinion there are a wealth of strategies available out there to learn from, which we can apply in your own strategy. There are many variables, seen and unseen, that go into whether or not an API will be "successful" or not, and I strongly reject the notion there are absolutes -- there are only agendas, usually of the behind the scenes kind.

I have a number of API plans and pricing pages that I did not include in the current release of this guide. I will consider evolving, and shifting it up regularly, like I try to do with my other guides. I know I learn a lot from having them in a single place, that I can easily flip through and experience the design patterns present across these 250 API platforms, and hopefully you do to. I'm currently planning an interactive micro-app version of this research, as well as the coffee table edition for the API socialite who also enjoys entertaining.

You can purchase a copy of The Pricing & Plans for 250 API platforms over at Gumroad, get a copy of this design guide crafted from my API research, while also supporting what I do -- thank you!

See The Full Blog Post