RSS

API Dependencies News

These are the news items I've curated in my monitoring of the API space that have some relevance to the API definition conversation and I wanted to include in my research. I'm using all of these links to better understand how the API related trainings are being conducted across organizations.

API Evangelist API Lifecycle Workshop on API Discovery

I’ve been doing more workshops on the API lifecycle within enterprise groups lately. Allowing me to refine my materials on the ground within enterprise groups, further flesh out the building blocks I recommend to API groups to help them craft their own API strategy. One of the first discussions I start with large enterprise groups is always in the area of API discovery, or commonly asked as, “do you know where all your APIs are?”

EVERY group I’m working with these days is having challenges when it comes to easy discovery across all the digital resources they possess, and put to use on a daily basis. I’m working with a variety of companies, organizations, institutions, and government agencies when it comes to the API discovery of their digital self:

  • Low Hanging Fruit (outline) - Understanding what resources are already on the public websites, and applications, by spidering existing domains looking for data assets that should be delivered as API resources.
  • Discovery (outline) - Actively looking for web services and APIs that exist across an organization, industry, or any other defined landscape. Documenting, aggregating, and evolving what is available about each API, while also publishing back out and making available relevant teams.
  • Communication (outline) - Having a strategy for reaching out to teams and engaging with them around API discovery, helping the remember to register and define their APIs as part of wider strategy.
  • Definitions (outline) - Work to make ensure that all definitions are being aggregated as part of the process so that they can be evolved and moved forward into design, development and production–investing in all of the artifacts that will be needed down the road.
  • Dependencies (outline) - Defining any dependencies that are in play, and will play a role in operations. Auditing the stack behind any service as it is being discovered and documented as part of the overall effort.
  • Support (outline) - Ensure that all teams have support when it comes to questions about web service and API discovery, helping them initially, as well as along the way, making sure all their APIs are accounted for, and indexed as part of discovery efforts.

API discovery will positively or negatively impact the rest of the API lifecycle at any organization. Not knowing where all of your resources are, and not having them properly defined for discovery at critical design, development, production, and integration movements, is an illness all companies are suffering from in 2018. We’ve deployed layers of services to deliver on enterprise growth, and put down a layer of web APIs to service the web, mobile, and increasingly device-based applications we’ve been delivering. Resulting in a tangled web of services, we need to tame before we can move forward properly.

Let me know if you need help with API discovery where you work. It is the fastest growing aspect of my API workshop portfolio. Aside from security, I feel like API discovery is the biggest challenge facing large enterprise groups learning to be more agile, flexible, and pushing forward with a microservices, and event-driven way of doing business. I definitely don’t have all the solutions when it comes to API discovery, but I knew have a lot of experience to share around how we are defining our enterprise capabilities and resources, and making them more discoverable across our entire API catalog.


API Evangelist And Streamdata.io API Lifecycle Workshops

I have been partnering with Streamdata.io to evolve how I work with enterprise groups on their API lifecycle strategy. After working closely with the Streadata.io sales team, it became clear that many enterprise organizations weren’t quite ready for the event-driven infrastructure Streamdata.io provides. Most grups were in desperate need of stepping back and developing their own formal strategy for delivering APIs across the enterprise, before they could every scale their operations and take advantage of things being more event-driven and real time.

In response, I set out to evolve my own API lifecycle material, gathered over the last eight years of studying the API space, and make it more accessible to the enterprise, as self-service short form and long form content, in-person workshops, and forkable blueprints that any enterprise can set in motion on their own. The results is a series of evolvable API projects, that we are using to drive our ongoing workshop engagements with enterprise API groups, focusing in on six critical areas of the API lifecycle:

  • Discovery - Knowing where all of your APIs and services are across groups.
  • Design - Focus in on an a design and virtualized API lifecycle before deployment.
  • Deployment - Understanding the many ways in which APIs can be deployed.
  • Operations - Thinking critically about properly operating API infrastructure.
  • Outreach - Helping understand how to reach out internally and externally.
  • Governance - Understanding how to measure, report, and evolve API operations.

Not all of our workshops will cover all of these areas. Depending on the time we have available, the scope of the team participating in a workshop(s), and how far along teams are in their overall API journey, the workshops might head in different directions, and expand or contract the depth in which we dive into each of these area (ie. not everyone is ready for governance). After several workshops this year, we have found these areas of the API lifecycle to be the most meaningful ways to organize a workshop, and help enterprise group think more critically about their API strategy.

Craft An API Strategy For Your Enterprise The purpose of our API lifecycle workshops is to help enterprise organizations develop a strategy. Bring in outside API knowledge, learn more about where an enterprise API group is in their overall API journey, and leave them with a structured artifact that helps them step back and look at the entire lifecycle of their APIs. Moving the API conversation across the enterprise forward in a meaningful way with three distinct actions:

  • Starter API Lifecycle Strategy - Provides a template API lifecycle strategy in GitHub or GitLab as README, and YAML file. Providing a framework to consider as you craft your own API strategy, providing a starting point for your journey. Generated from eight years of research on the API space, providing a living document that can be used to execute and evolve the overall API lifecycle strategy for an enterprise organization.
  • API Lifecycle Workshop - Conduct a single, or multi-day API lifecycle workshop on-site, with as many enterprise and / or partner stakeholders as possible. We will come on site, and walk teams through each stop along a modern API lifecycle, helping customize, personalize, and make the API strategy better fit the enterprises strategy.
  • Evolve API Lifecycle Strategy - Coming out of the workshop, you will be given an updated API lifecycle README, and YAML file. Providing a human and machine readable framework that represents your API lifecycle strategy, helping provide a scaffolding for future discussions. Producing a usable artifact out of the gathering, encapsulating the research and experience we bring to the table, adding what we learned during the workshop, and hopefully continually being used to drive the API strategy road map.
  • Provide Execution & Support - After the workshop is done, and we have an updated API lifecycle, we are here to support. We can answer questions via the repository we leave an API strategy artifact, as well as email. We are happy to conduct virtual meetings to help check in on where you are at, and of course we are happy to always come back and conduct future workshops as you need.

We are happy to continue the conversation around the API lifecycle artifact we will leave with you. We don’t expect you to use everything we propose. We are more interested in teaching you about what is possible, and continuing to work with you to refine, evolve, and make the API lifecycle your own. We’ve just worked hard to identified many different ways to operating API infrastructure at scale, and continue to help standardize and make it more accessible by large enterprise organizations.

Helping You In Your Journey The API lifecycle strategy we will leave behind will possess all the knowledge we’ve aggregated across API research, gathered across leading API providers, and honed by conducting API workshops within the enterprise. Embedded within this API lifecycle artifact we’ll leave you with some added elements that will help you in your journey, going beyond just advice on process, and helping the rubber meet the road.

  • Areas - Help you see the separate the different layers of your API operations by quantifying the real world currents that exist across your API Platform.
  • Stops - Teach how to follow in the footsteps of other successful API providers, while also defining your own journey, when it comes to delivering APIs across the lifecycle.
  • Links - Provide a wealth of references to external resources, attached to each stop along the API lifecycle, bring our API research into your organization, allowing you to put to use inline as you are building your API strategy.
  • Services - Embedding links to API services that you are already using, and introducing you to other useful API services along the way. Making sure specific services are associated with each stop along the API lifecycle, across the different areas, and even sub-linking to specific features that can help accomplish a specific aspect of API operations.
  • Tooling - Embedding links to open source API tools, specifications, and other solutions that can be used to accomplish a specific aspect of operating an API platform. Brining in open source solutions that can be considered as you are crafting the API strategy for your enterprise organization.

While not all organizations will be ready to use a YAML API lifecycle artifact as part of their API orchestration, it helps to have the API lifecycle well defined, even if many steps are still manual. It helps teams think more critically about how they approach the deliver of APIs, while also being something that can be downloaded, forked, and reused by different groups across the enterprise. Eventually it is something that can be further automated, measured, and used to help quantify the maturity level of each APIs, as well as API across distributed teams.

Next Steps For Developing A Strategy If you are interested in what we are offering with our API lifecycle workshops, simply let me know, and I can get the ball rolling by getting you the starter API lifecycle strategy, and provide more information about scheduling and pricing for our engagement. Then we can begin to figure out how we can get something into the calendar, and hopefully jumpstart the API conversation with your team. If there are any other things you’d like to see, or have questions about, just let me know. Like the API journey, my API lifecycle workshops are always evolving and adapting.


API Evangelist And Streamdata.io API Lifecycle Workshops

I have been partnering with Streamdata.io to evolve how I work with enterprise groups on their API lifecycle strategy. After working closely with the Streadata.io sales team, it became clear that many enterprise organizations weren’t quite ready for the event-driven infrastructure Streamdata.io provides. Most groups were in desperate need of stepping back and developing their own formal strategy for delivering APIs across the enterprise, before they could every scale their operations and take advantage of things being more event-driven and real time.

In response, I set out to evolve my own API lifecycle researched, gathered over the last eight years of studying the API space, and make it more accessible to the enterprise, as self-service short form and long form content, in-person workshops, and forkable blueprints that any enterprise can set in motion on their own. The results is a series of evolvable API projects, that we are using to drive our ongoing workshop engagements with enterprise API groups, focusing in on six critical areas of the API lifecycle:

  • Discovery - Knowing where all of your APIs and services are across groups.
  • Design - Focus in on an a design and virtualized API lifecycle before deployment.
  • Deployment - Understanding the many ways in which APIs can be deployed.
  • Operations - Thinking critically about properly operating API infrastructure.
  • Outreach - Helping understand how to reach out internally and externally.
  • Governance - Understanding how to measure, report, and evolve API operations.

Not all of our workshops will cover all of these areas. Depending on the time we have available, the scope of the team participating in a workshop(s), and how far along teams are in their overall API journey, the workshops might head in different directions, and expand or contract the depth in which we dive into each of these area (ie. not everyone is ready for governance). After several workshops this year, we have found these areas of the API lifecycle to be the most meaningful ways to organize a workshop, and help enterprise group think more critically about their API strategy.

Craft An API Strategy For Your Enterprise The purpose of our API lifecycle workshops is to help enterprise organizations develop a strategy. Bring in outside API knowledge, learn more about where an enterprise API group is in their overall API journey, and leave them with a structured artifact that helps them step back and look at the entire lifecycle of their APIs. Moving the API conversation across the enterprise forward in a meaningful way with three distinct actions:

  • Starter API Lifecycle Strategy - Provides a template API lifecycle strategy in GitHub or GitLab as README, and YAML file. Providing a framework to consider as you craft your own API strategy, providing a starting point for your journey. Generated from eight years of research on the API space, providing a living document that can be used to execute and evolve the overall API lifecycle strategy for an enterprise organization.
  • API Lifecycle Workshop - Conduct a single, or multi-day API lifecycle workshop on-site, with as many enterprise and / or partner stakeholders as possible. We will come on site, and walk teams through each stop along a modern API lifecycle, helping customize, personalize, and make the API strategy better fit the enterprises strategy.
  • Evolve API Lifecycle Strategy - Coming out of the workshop, you will be given an updated API lifecycle README, and YAML file. Providing a human and machine readable framework that represents your API lifecycle strategy, helping provide a scaffolding for future discussions. Producing a usable artifact out of the gathering, encapsulating the research and experience we bring to the table, adding what we learned during the workshop, and hopefully continually being used to drive the API strategy road map.
  • Provide Execution & Support - After the workshop is done, and we have an updated API lifecycle, we are here to support. We can answer questions via the repository we leave an API strategy artifact, as well as email. We are happy to conduct virtual meetings to help check in on where you are at, and of course we are happy to always come back and conduct future workshops as you need.

We are happy to continue the conversation around the API lifecycle artifact we will leave with you. We don’t expect you to use everything we propose. We are more interested in teaching you about what is possible, and continuing to work with you to refine, evolve, and make the API lifecycle your own. We’ve just worked hard to identified many different ways to operating API infrastructure at scale, and continue to help standardize and make it more accessible by large enterprise organizations.

Helping You In Your Journey The resulting API lifecycle strategy we leave behind after the workshop is done will possess all the knowledge we’ve aggregated across API research, gathered across leading API providers, and polished by conducting API workshops within the enterprise. Embedded within this API lifecycle artifact we’ll leave you with some added elements that will help you in your journey, going beyond just advice on process, and helping the rubber meet the road.

  • Links - Provide a wealth of references to external resources, attached to each stop along the API lifecycle, bring our API research into your organization, allowing you to put to use inline as you are building your API strategy.
  • Services - Embedding links to API services that you are already using, and introducing you to other useful API services along the way. Making sure specific services are associated with each stop along the API lifecycle, across the different areas, and even sub-linking to specific features that can help accomplish a specific aspect of API operations.
  • Tooling - Embedding links to open source API tools, specifications, and other solutions that can be used to accomplish a specific aspect of operating an API platform. Brining in open source solutions that can be considered as you are crafting the API strategy for your enterprise organization.

While not all organizations will be ready to use a YAML API lifecycle artifact as part of their API orchestration, it helps to have the API lifecycle well defined, even if many steps are still manual. It helps teams think more critically about how they approach the deliver of APIs, while also being something that can be downloaded, forked, and reused by different groups across the enterprise. Eventually it is something that can be further automated, measured, and used to help quantify the maturity level of each APIs, as well as API across distributed teams.

Next Steps For Developing A Strategy If you are interested in what we are offering with our API lifecycle workshops, simply let me know, and I can get the ball rolling by getting you starter API lifecycle strategy kit, and provide more information about scheduling and pricing for our engagement. Then we can begin to figure out how we can get something into the calendar, and hopefully jumpstart the API conversation with your team. If there are any other things you’d like to see, or have questions about, just let me know. Like the API journey, my API lifecycle workshops are always evolving and adapting.


Some Ideas For API Discovery Collections That Students Can Use

This is a topic I’ve wanted to set in motion for some time now. I had a new university professor city my work again as part of one of their courses recently, something that floated this concept to the top of the pile again–API discovery collections meant for just for students. Helping k-12, community college, and university students quickly understand where to find the most relevant APIs to whatever they are working on. Providing human, but also machine readable collections that can help jumpstart their API education.

I use the API discovery format APIs.json to profile individual, as well as collections of APIs. I’m going to kickstart a couple of project repos, helping me flesh out a handful of interesting collections that might help students better understand the world of APIs:

  • Social - The popular social APIs like Twitter, Facebook, Instagram, and others.
  • Messaging - The main messaging APIs like Slack, Facebook, Twitter, Telegram, and others.
  • Rock Star - The cool APIs like Twitter, Stripe, Twilio, YouTube, and others.
  • Amazon Stack - The core AWS Stack like EC2, S3, RDS, DynamoDB, Lambda, and others.
  • Backend Stack - The essential App stack like AWS S3, Twilio, Flickr, YouTube, and others.

I am going to start there. I am trying to provide some simple, usable collections or relevant APIs for students are just getting started If there are any other categories, or stacks of APIs you think would be relevant for students to learn from I’d love to hear your thoughts. I’ve done a lot of writing about educational and university based APIs, but I’ve only lightly touched upon what APIs should students be learning about in the classroom.

Providing ready to go API collections will be an important aspect of the implementation of any API training and curriculum effort. Having the technical details of the API readily available, as well as the less technical aspects like signing up, pricing, terms of service, privacy policies, and other relevant building blocks should also be front and center. I’ll get to work on these five API discovery collections for students. Get the title, description, and list of each API stack published as a README, then I’ll get to work on publishing the machine, and human readable details for the technology, business, and politics of using APIs.


Not Liking OpenAPI (fka Swagger) When You Have No Idea What It Does

People love to hate in the API space. Ok, I guess its not exclusive to the API space, but it is a significant aspect of the community. I receive a regular amount of people hating on my work, for no reason at all. I also see people doing it to others in the API space on a regular basis. It always makes me sad to see, and have always worked to try to be as nice as I can to counteract the male negativity and competitive tone that often exists. While I feel bad for the people on the receiving end of all of this, I often times feel bad for the people on the giving end of things, as they are often not the most informed and up to speed folks, who seem to enjoy opening their mouth before they understand what is happening.

One thing I notice regularly, is that these same people like to bash on is OpenAPI (fka Swagger). I regularly see people (still) say how bad of an idea it is, and how it has done nothing for the API space. One common thread I see with these folks, which prevents me from saying anything to them, is that it is clear they really don’t have an informed view of what OpenAPI is. Most people spend a few minutes looking it, maybe read a few blog posts, and then establish their opinions about what it is, or what it isn’t. I regularly find people who are using it as part of their work, and don’t actually understand the scope of the specification and tooling, so when someone is being vocal about it and doesn’t use actually it, it is usually pretty clear pretty quickly how uninformed they are about the specification, tooling, and scope of the community.

I’ve been tracking on it since 2011, and I still have trouble finding OpenAPI specifications, and grasping all of the ways it is being used. When you are a sideline pundit, you are most likely seeing about 1-2% of what OpenAPI does–I am a full time pundit in the game and I see about 60%. The first sign that someone isn’t up to speed is they still call it Swagger. The second sign is they often refer to it as documentation. Thirdly, they often refer to code generation with Swagger as a failure. All three of these views date someone’s understanding to about a 2013 level. If someone is forming assumptions, opinions, and making business decisions about OpenAPI, and being public about it, I’d hate to see what the rest of their technology views look like. In the end, I just don’t even feel like picking on them, challenging them on their assumptions, because their regular world is probably already kicking their ass on a regular basis–no assistance is needed.

I do not feel OpenAPI is the magical solution to fix all the challenges the API space, but it does help reduce friction at almost every stop along the API lifecycle. In my experience, 98% of the people who are hating on it do not have a clue what OpenAPI is, or what it does. I used to challenge folks, and try to educate them. Over the years I’ve converted a lot of folks from skeptics to believers, but in 2018, I think I’m done. If someone is openly criticizing it, I’m guessing it is more about their relationship to tech, and their lack of awareness of delivering APIs at scale, and they probably exist in a pretty entrenched position because of their existing view of the landscape–they don’t need me piling on. However, if people aren’t aware of the landscape, and ask questions about how OpenAPI works, I’m always more than happy to help open their eyes to how the API definition is serving almost every stop along the API lifecycle from design to deprecation, and everything in between.


People Still Think APIs Are About Giving Away Your Data For Free

After eight years of educating people about sensible API security and management, I’m always amazed at how many people I come across who still think public web APIs are about giving away access to your data, content, and algorithms for free. I regularly come across very smart people who say they’d be doing APIs, but they depend on revenue from selling their data and content, and wouldn’t benefit from just putting it online for everyone to download for free.

I wonder when we stopped thinking the web was not about giving everything away for free? It is something I’m going to have to investigate a little more. For me, it shows how much education we still have ahead of us when it comes to informing people about what APIs are, and how to properly manage them. Which is a problem, when many of the companies I’m talking to are most likely doing APIs to drive internal systems, and public mobile applications. They are either unaware of the APIs that already exist across their organization, or think that because they don’t have a public developer portal showcasing their APIs, that they are much more private and secure than if they were openly offering them to partners and the public.

Web API management has been around for over a decade now. Requiring ALL developers to authenticate when accessing any APIs, and the ability to put APIs into different access tiers, limit that the rate of consumption, while logging and billing for all API consumption isn’t anything new. Amazon has been extremely public about their AWS efforts, and the cloud isn’t a secret. The fact that smart business leaders see all of this and do not see that APIs are driving it all represents a disconnect amongst business leadership. It is something I’m going to be testing out a little bit more to see what levels of knowledge exist across many fortune 1000 companies, helping paint of picture of how they view the API landscape, and help me quantify their API literacy.

Educating business leaders about APIs has been a part of my mission since I started API Evangelist in 2010. It is something that will continue to be a focus of mine. This lack of awareness is why we end up with damaging incidents like the Equifax breach, and the Cambridge Analytica / Facebook scandal. Its how we end up with so many trolls on Twitter, and an out of balance API ecosystems across federal, state, and municipal governments. It is a problem that we need to address in the industry, and work to help educate business leaders around common patterns for securing and managing our API resources. I think this process always begins with education and API literacy, but is a symptom of the disconnect around storytelling about public vs private APIs, when in reality there are just APIs that are secured and managed properly, or not.


API Transit Basics: Training

This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through.

Think of support as a reactive area, while training will be the proactive area of the API life cycle. Ensuring there is a wealth of up to date material for API developers and consumers across all stops along the API life cycle. Investing in internal, and partner capacity when it comes to the fundamentals of APIs, as well as the finer details of each stop along the API life cycle, and CI/CD pipelines will pay off big time down the road.

Every API should be included in training materials, workshops, and potentially part of conference talks given my product owners. If your API delivers value within your organization, to partners, and 3r party developers you should be training folks on putting this value to use. Here are some of the training areas I’m seeing emerge within successful API operations:

  • Workshops - Conduct more of the workshops that I conducted with external consultants like me, as well as make sure they are conducted internally by each group. The first day of the our workshop was a great example of this in action.
  • Curriculum - Establish common approaches to designing, developing, and evolving curriculum for teaching about the API lifecycle, as well as using each individual API. Provide forkable templates that developers can easily put to work as part of their work, and make support materials a pipeline asset that gets deployed along with documentation, and other assets.
  • Conferences - Make sure you are sending team members to the latest conferences. In my conversations during the workshop, this didn’t seem like a problem, but something I think should be included anyways.

Like every other stop along this journey, API training can be a pipeline artifact and be developed, deployed, and evolved alongside all other code, documentation, and available solutions. Pushing everyone to not just attend trainings, but also work to develop and deliver curriculum as part of trainings helps make sure everyone is able to communicate what they do across the company. Everyone should be contributing to, executing, and participating in API training, no matter what their skill level, or ability to get up in front of people and speak.

API training will increase adoption, and save resources down the road. It will compliment platform communications, and strengthen support, while providing valuable feedback that can be included as part of the road map. My favorite part about doing API training is that it forces me as a developer to think through my ideas, consider how I can articulate and share them with others, which if you think about it, is an essential part of the API journey, and something we should bake into operations by default.


I Can Keep Evangelizing The Same API Stories For The Next Decade In Government

I spoke on a panel at the Red Hat, Fed Scoop Government Symposium in Washington D.C. yesterday. I had some great conversations with technology vendors, as well as government agencies about everything API. I enjoy being outside the Silicon Valley echo chamber when it comes to technology because I enjoy helping folks understand the basics of what is going on with the basics of APIs, over getting too excited over the latest wave of new technology, and a constant need to be moving forward before ever getting a handle on the problems on the table.

It can be hard to to repeat some of the same stories I’ve been telling for the last seven years while in these circles, but honestly the process helps me refine what I’m saying, and continue to actively think through the sustained relevancy of the stories I’ve been telling. After this round of discussions in D.C. I feel there are a some themes in my work, I can keep refining, and crafting stories for sharing in the government space.

  • Open - I know its a tired term, but learning to be more open with other agencies, partners, and the public is an essential component of doing APIs in the federal government.
  • Documentation - Do not reinvent the wheel with documentation, and leverage OpenAPI to help you keep documentation usable, up to date, and valuable to developers using existing open source API documentation solution.
  • Support - Provide email, office hours, Twitter, ticketing, Github issues, and other common support building blocks for API consumers, making sure people know they can get help when they need.
  • Communication - Talk to your consumers. Have a blog, Twitter account, and other social channels for communicating internally, with partners, and publicly with API consumers.
  • Experiment - See your APIs as an R&D extension of an agency, and allow for experimentation with APIs, as well as the consumption of the APIs. Think about sandboxes, data virtualization, and other ways of minimizing agency risk.
  • Education - Make sure you are reaching out, educating, and providing training for all API stakeholders, ensuring that everyone is up to speed, and making no assumptions about what people know, or do not know.

None of this is technical. This is all basic API knowledge that any business or technical API stakeholder can take ownership of. These are all things that I see kill API efforts in the public, as well as private sector. These are all things that IT and developer folks scoff at and feel are unnecessary, and business users do not always see as an essential part of technical implementations. These are all deficient elements present across the 100 developer portals, and the 500 APIs I keep an eye on across the federal government. They are common building blocks of API operations that I’ll keep beating a drum about on my blog, and in person at events I attend in D.C.

The API environment in D.C. would frustrate your average API developer, architect, and evangelist. I get frustrated at the speed of things, and having to say the same things over and over. However, I also understand the scope of what the federal government does, and the number of people we have to get up to speed on things. The number of APIs available is actively growing, but the consistency, usability, and effectiveness of APIs isn’t keeping pace. To keep things in balance we are going to need even more evangelism around operating government in an online environment, and how APIs can help provide access to data, content, and even algorithms across all branches of government in a safe and secure ways.


Learning To Play Nicely With Others Using APIs

This is a topic I talk about often, write about rarely, but experience on a regular basis doing APIs. It has to do with encounters I have with people in companies who do not know how to share and play nicely with other companies and people, and want to do APIs. For a variety of reasons these folks approach me to learn more about APIs, but are completely unaware of what it takes, and how it involves working with external actors. Not all of these APIs are public, but many of them involve engaging with individuals outside the corporate firewall, possess a heavy focus on the technical, and business of doing APIs, but rarely ever consider the human and more political aspects of engagements with APIs.

I find that people tend to have wildly unrealistic expectations of technology, and believe that APIs will magically connect them to some unlimited pool of developers, or seamlessly connect disparate organizations across vast distances. People come to me hoping I will be able to explain it all to them in a single conversation, or provide in a short white paper, which is a state of being that also makes individual very susceptible to vendor promises. People want to believe that APIs will fix the problems they have introduced into their operations via technology, and effortlessly connect them with outside revenue streams and partnerships, unencumbered by the same human challenges they face within their firewalls.

Shortly after getting to know people it often becomes apparent that they possess a lot of baggage, legacy processes and beliefs, that they are often unaware of. Or, I guess more appropriately they are unaware that these legacy beliefs are not normal, and are something everybody faces. Where they are usually pretty uniquely dysfunctional to a specific organization. People usually have hints that these problems aren’t normal, but just aren’t equipped to operate outside their regular sphere of influence, and within days or weeks of engagement, their baggage becomes more visible. They start expecting you to jump through the same hoops they do. Respond to constraints that exist in their world. See data, content, and algorithms through the same lens as their organization. At this point folks are usually unaware they’ve opened the API door on their world, and the light is shining in on their usually insulated environment–revealing quite a mess.

This is why you’ll hear me talk of “dating” folks when it comes to API engagements. Until you start opening, and leaving the door open on an organization for multiple days at a time, you really can’t be sure what is happening behind those closed doors. I am also not always confident that someone can keep internal dysfunction from finding its way out. I don’t expect that all organization be dysfunction free, I’m just looking for folks who are aware of their dysfunction, and are looking to actively control, rate limit, and minimize the external impacts. As well as being willing to work through some of this dysfunction, as they engage with external actors. I have to also acknowledge that this game is a two way street, and I also encounter API consumers who are unable to leave their baggage at home, and bring their seemingly natural internal dysfunction to the table when looking to put external resources to work across their operations. In general, folks aren’t always equipped to play nicely with others by default, it takes some learning, and evolving, but this is why we do APIs. Right?

This is why I suggest people become API consumers, before they become API providers, so that they can truly understand what it is like to be on both sides of the equation. API providers who haven’t experienced what its like to be on the receiving end of an external API, rarely make for empathetic API providers. Our companies, organizations, institutions, and government agencies often insulate us from the outside world, which works in many positive ways, but as you are aware, it also works in some negative, and very damaging political ways. The trick with doing APIs, is to slowly change this behavior, and being able to let in outside ideas, and resources, without too much disruption, internally or externally. Then over time, learn to play nicely with others, and build relationships with other groups, and individuals who might benefit our organizations, and we might also help bring value to their way of doing things as well.


Most API Developers Will Not Care As Much As You Do

I believe in the potential of what APIs can do, and care about learning how we can do things right. Part of it is my job, but part of it is me wanting to do things well. Master my approach to delivering APIs, using my well-rounded API toolbox. Reading the approach of other leading API providers, and honing my understanding of healthy, and not so healthy practices. I thoroughly enjoy studying what is going on and then applying it across what I do. However I am reminded regularly that most people are not interested in knowing, and doing things right–they just want things done.

As many of us discuss the finer details of API design, and the benefits of one approach over the other, other folks would rather us just point them to the solution that will work for them. They really don’t care about the details, or mastering the approach, they just want it to work in their situation. Whether it is the individual, the project or organization they are working in, the environment is just not conducive to learning, understanding, and growth. They are just interested in services and tools that can deliver the desired solution for as cheap as possible–free, and open source whenever available.

You can see this reality playing out across the space. An example is OpenAPI (fka Swagger). It has largely been successful because of Swagger UI. Most people think OpenAPI is all about documentation, with their understanding reflecting the solution they delivered, not the full benefits brought to the table as part of the process of implementing the specification. This is just one example of how folks across the API space are interested in solutions, rather than the journey. This is why many API programs will stagnate and fail, because folks do them thinking they’ll achieve some easier way of doing things, easy integrations, effortless innovation, or some other myth around API Valhalla.

I feel like much of this reality is set into motion through our education system. We don’t always teach people to learn, we tend to teach them job skills that we (companies) perceive are relevant today. Technology training tends to become about software solutions, brands, and platforms, and rarely concepts. Then I feel like this is baked into company operations because of the escalated pace introduced by startup funding, all the way up to the constant quest for profits of publicly traded companies. An incentive model that encourages folks to just do, not necessary do right. Achieve short term goals, quarterly and annual metrics, and ignore the technical debt we created–that will be someone elses problem.

Helping developers learn about APIs feels like our healthcare system sometimes to me. Developers are focused on fixing problems, treating symptoms, and living with good enough outcomes. Nothing preventative. No healthy diet or exercise. Just solving the problems that are in front of us. Looking for solutions to these immediate needs. I need API documentation. I need some sort of automated testing, or security scanner. I just need that API to be performant. I’m not interested in learning about the web, standards, or other things that would help me in my work. I just want this to work, so I can move on to the next problem. It’s a pretty big problem in the API space which I really don’t have any solution for. I’ll just keep learning, educating, and sharing with folks, but regularly reminding myself that not everyone will care about this stuff as much as I do, and that is just the way things are.


How Do We Help Folks Understand That APIs Are A Journey?

I was hanging out with my friend Mike Amundsen (@mamund) in Colorado last month and we ended up discussing folks uncertainty with APIs. You see, many folks that he has been talking to were extremely nervous about all the unknowns in the world of APIs, and were looking for more direction regarding what they should be doing (or not doing). Not all people thrive in a world of unknown unknowns, and not even in a world of known unknowns. Many just want a world of known knowns. This is something that makes the API landscape a very scary thing to some folk, and world where they will not thrive and be successful unless we can all begin to find a way to help them understand that this is all a journey.

I love figuring all of this API stuff out, and I know Mike does too. We like thinking about the lofty concepts, as well as figuring out how to piece all the technical elements together in ways that work in a variety of business sectors. Many folks we are pushing APIs on aren’t like us, and just want to be told what to do. They just want the technology solution to their problem. A template. A working blueprint. It freaks them out to have so many options, possibilities, patterns, and directions they take things. I feel like we are setting folks up for failure when we talk them into embarking on an API journey without the proper training, equipment, support, and guidance.

I think about the last seven years doing this, and how much I’ve learned. Realizing this makes me want to keep doing APIs, just so I can keep learning new things. I thought I understood REST when I started. I didn’t. I thought I understand the web when I started, I didn’t (still don’t). I was missing a lot of the basics, and no matter what folks told me, or how precise their language was, I still needed to bang my head on something over and over before I got it. I was missing a significant amount of why hypermedia can be a good approach without truly understanding content negotiation, and link relations. Realizing how much I still need to explore and learn has only emboldened me on my journey, but I’m not convinced this will be the case with everyone. We are wrong to assume everyone is like us.

As technologists and autodidacts we often overestimate our own ability, as well as what others are capable of. We realize APIs are not a destination, but a journey. However, we suck at explaining this to others. We are horrible at understanding all of the stepping stones that got us here, and recreating them for others. I put myself into this group. I think about this stuff full time, and I still regularly stumble when it comes to on-boarding folks with what API are, and properly helping them in their journey. I still do not have a proper set of on-boarding lessons for folks, beyond my API 101 stuff. I talk a lot of talk about the API life cycle, the API economy, and all the business and politics of APIs, but I still can’t point folks to where the yellow brick road is. We have to get better at this if we expect folks to ever catch up.

This is one reason I feel Zapier, and other iPaaS providers are so important. We should be helping people understand APIs and integration in context of the problems they are trying to solve, not in terms of REST, SDKs, or any of the other technical jargon we spew. With Zapier, folks can play with Zaps (recipes) that deliver meaningful API integration that actually solve a problem in their world. They can play with what is possible, without learning all the technical pieces first. They can evolve in their business world, while also progressing on their API journey. IDK. I’m just trying to find ways to help folks better understand what APIs are. I’ll never make everything known to them, but I’m hoping that I can help make folks a little less nervous about the known unknowns, and who knows maybe some day they’ll feel brave enough, and confident in their API awareness that they’ll be able to operate in a world of the unknown unknowns, and settle in on the perpetual journey that are APIs.


Talking With More Federal Agencies About API Micro Consulting

I have been having more conversations with federal agencies as part of my work with my Skylight partners about API related microconsulting. One recent conversation, which I won’t mention the agency, because I haven’t gotten approval, involved bug bounties on top of an API they are rolling out. The agency isn’t looking for the regular technology procurement lifecycle around this project, they are just looking for a little bit of research and consulting to help ensure they are on the right track when it comes to hardening their API approach.

Micro consulting like this will usually not exceed $5,000.00 USD, and will always be a short term commitment. From my vantage point micro consulting will always be API related, and in this particular case involves studying how other API providers in the private sector are leveraging bug bounties to help harden their APIs either before they go public, or afterwards in an ongoing fashion. After I do the research I will be taking this work back to my team of consultants at Skylight, and we’ll put together formal report and presentation that we will bring back to the federal government agency to put into motion.

This approach to doing APIs in the federal government (or any government) is a win-win. It fits with my approach to doing research at API Evangelist, and it provides API expertise for federal agencies in small, affordable, and bite-size chunks. Government agencies do not have to wait months, or years, and spend massive amounts of money to gain access to API expertise. For Skylight, it gets our foot in the door within government, and helps demonstrate the expertise we bring to the table. Something that will almost always turn into additional micro procurement relationships, as well as potentially larger scale, ongoing project relationships.

Personally, I like my API consulting just like my APIs, small, and doing one thing well. I don’t like consulting contracts that try to do too much. I also like getting paid in chunks that can usually be put on the corporate credit card, and avoid too much purchase order, vendor system, 30, 60, and 90 day wrangling–or worse, not getting paid at all. You’ll hear me beating the micro consulting, and micro procurement drum a lot more in coming months. I’m going to be working to educate more government agencies, and even the enterprise of the potential when it comes to API related content creation, storytelling, training, and research. I’m predicting it will have the same effect as APIs are having on how companies, organizations, institutions, and government agencies are doing business in the digital economy.


If you think there is a link I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.