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 space is testing their APIs, going beyond just monitoring and understand the details of each request and response.28 Aug 2018
Nobody likes to be told that their APIs are unreliable, and unavailable on a regular basis. However, it is one of those pills that ALL APIs have to swallow, and EVERY API provider should be paying for an external monitoring service to tell us when are APIs are up or down. Having a monitoring service to tell us when our APIs are having problems, complete with a status dashboard, and history of our API’s availability are essential building blocks of any API provider. If you expect consumers to use your API, and bake it into their systems and applications, you should committed to a certain level of availability, and offering a service level agreement if possible.
My friends over at APImetrics monitor APIs across multiple industries, but we’ve been partnering to keep an eye on federal government APIs, in support of my work in DC. They’ve recently shared an informative dashboard tracking on the performance of federal government APIs, providing an interesting view of the government API landscape, and the overall reliability of APIs they provide.
They continue by breaking down the performance of federal government APIs, including how the APIs perform across multiple North American regions across four of the leading cloud providers:
Helping us visualize the availability of federal government APIs for the last seven days, by applying their APImetrics CASC score:
I know it sucks being labeled as one of the worst performing APIs, but you also have the opportunity to be named one the best performing APIs. ;-) This is a subject that many private sector companies struggle with, and the federal government has an extremely poor track record for monitoring their APIs, let alone sharing the information publicly. Facing up to this stuff sucks, and you are forced to answer some difficult questions about your operations, but it is also something can’t be ignored away when you have a public API
You can view the US Government API Performance Dashboard for July 2018 over at APImetrics. If you work for any of these agencies and would like to have a conversation your API monitoring, testing, and performance strategy, I am happy to talk. I know the APImetrics team are happy to help to, so don’t stay in denial about your API performance and availability. Don’t be embarrassed. Tackle the problem head on, improve your overall quality of service, and then having an API monitoring and performance dashboard publicly available like this won’t hurt nearly as much–it will just be a normal part of operating an API that anyone can depend on.
I’m fascinated by the dominating power of programming languages. There are many ideological forces at play in the technology sector, but the dogma that exists within each programming language community continues to amaze me. The potential absence of programming language dogma within the world of APIs is one of the reasons I feel it has been successful, but alas, other forms of dogma tends to creep in around specific API approaches and philosophies, making API evangelism and adoption always a challenge.
The absence of programming languages in the API design, management, and testing discussion is why they have been so successful. People in these disciplines have ben focused on the language agnostic aspects of just doing business with APIs. It is also one of the reasons the API deployment conversation still is still so fragmented, with so many ways of getting things done. When it comes to API deployment, everyone likes to bring their programming language beliefs to the table, and let it affect how we actually deliver this API, and in my opinion, why API gateways have the potential to make a comeback, and even excel when it comes to playing the role of API intermediary, proxy, and gateway.
Programming language dogma is why many groups have so much trouble going API first. They see APIs as code, and have trouble transcending the constraints of their development environment. I’ve seen many web or HTTP APIs called Java API, Python APIs, or reflect a specific language style. It is hard for developers to transcend their primary programming language, and learn multiple languages, or think in a language agnostic way. It is not easy for us to think out of our boxes, and consider external views, and empathize with people who operate within other programming or platform dimensions. It is just easier to see the world through our lenses, making the world of APIs either illogical, or something we need to bend to our way of doing things.
I’m in the process of evolving from my PHP and Node.js realm to a Go reality. I’m not abandoning the PHP world because many of my government and institutional clients still operate in this world, and I’m using Node.js for a lot of serverless API stuff I’m doing. However I can’t ignore the Go buzz I keep coming stumbling upon. I also feel like it is time for a paradigm shift, forcing me out of my comfort zone and push me to think in a new language. This is something I like to do every five years, shifting my reality, keeping me on my toes, and forcing me to not get too comfortable. I find that this keeps me humble and thinking across programming languages, which is something that helps me realize the power of APIs, and how they transcend programming languages, and make data, content, algorithms, and other resources more accessible via the web.
I’m kicking off a micro-procurement project with the Department of Veterans Affairs (VA) this week. I’m going to to be conducting one of my API low hanging fruit campaigns for them, where I help them identify the best possible data sets available across their public websites for turning into APIs. The project is one of many small projects the federal agency is putting out there to begin working on their agency wide API platform they are calling Lighthouse. Laying the groundwork for better serving veterans through a robust stack of microservices that each do one thing really well, but can be used in concert to deliver the applications the agency needs to meet their mission.
While not specifically a project to develop a microservice. The landscape analysis project is an API focused research project, that is testing a new procurement model called microprocurement. At my government consulting agency partnership Skylight Digital, my partner in crime Chris Cairns has been pushing for a shift in how government tackles technology projects, pushing them to do in smaller chunks that essentially can be put on the credit card in less than 10K increments. So far we’ve been doing consulting, research, and training related projects like how to create a bug bounty program, and internal evangelism strategies. Now we are kicking our campaign into high gear and pushing more agencies to think about microprocurement for microservices–the VA was the first agency to buy into this new way of thinking about how government IT gets delivered.
I am working with all of my partners to help me craft potential services that would fit into the definition of a microprocurement project. I’ve been working to educate people about the process so that more API experts are on hand to respond when agencies publish microprocurement RFPs on Github like the VA did, but I also want to make sure and have a suite of microprocurement packages that federal agencies can choose from as well. I’ve been working with my partner Dave O’Neill over at API Metrics to provide me with some detail on an API testing microprocurement package that federal agencies could buy into for less than 10K, providing the follow value:
- API discovery and creation of a Postman collection
- Annual monitoring for up to 10 APIs including the following:
- Weekly and monthly emailed quality statements – CASC scores and SLOs/SLA attainment
- Interface to named operations tooling for alerts
- Public dashboards for sharing API status and SLA with all stakeholders.
Providing a pretty compelling annual API monitoring package that government agencies could put on the credit card, and help ensure the quality of service provided across federal agencies when it comes to providing APIs. Something that is desperately needed across federal agencies who in my experience are mostly conducting “API nonitoring”, where they are not monitoring anything. Ideally, ALL federal agencies provide an SLA with the public and private APIs they are serving up, and relying on outside entities like API Metrics to be doing the monitoring from an external perspective, and potentially even different regions of the US–ensuring everyone has access to government services.
I’ll publish anther story after I kick off my work with the VA. I’ll also keep beating the drum about microprocurement opportunities like this one with API Metrics. If you are an API service provider who has an interesting package you think federal agencies would be interested in–let me know. Also, if you are a government agency and would like to learn more about how to conduct microprocurement projects feel free to drop me a line, or reach out to Chris Cairns (@cscairns) over at Skylight Digital–he can set you up. We are just getting going with this types of projects, but I’m pretty optimistic about the potential they can bring to the table when it comes to delivering IT projects–an approach that reflects the API way of doing things in small, meaningful chunks, and won’t break the bank.
404: Not Found
I’ve talked about how generating an OpenAPI (fka Swagger) definition from code is still the dominate way that microservice owners are producing this artifact. This is a by-product of developers seeing it as just another JSON artifact in the pipeline, and from it being primarily used to create API documentation, often times using Swagger UI–which is also why it is still called Swagger, and not OpenAPI. I’m continuing my campaign to help the projects I’m consulting on be more successful with their overall microservices strategy by helping them better understand how they can work in concert by focus in on OpenAPI, and realizing that it is the central contract for their service.
Each Service Beings With An OpenAPI Contract There is no reason that microservices should start with writing code. It is expensive, rigid, and time consuming. The contract that a service provides to clients can be hammered out using OpenAPI, and made available to consumers as a machine readable artifact (JSON or YAML), as well as visualized using documentation like Swagger UI, Redocs, and other open source tooling. This means that teams need to put down their IDE’s, and begin either handwriting their OpenAPI definitions, or being using an open source editor like Swagger Editor, Apicurio, API GUI, or even within the Postman development environment. The entire surface area of a service can be defined using OpenAPI, and then provided using mocked version of the service, with documentation for usage by UI and other application developers. All before code has to be written, making microservices development much more agile, flexible, iterative, and cost effective.
Mocking Of Each Microservice To Hammer Out Contract Each OpenAPI can be used to generate a mock representation of the service using Postman, Stoplight.io, or other OpenAPI-driven mocking solution. There are a number of services, and tooling available that takes an OpenAPI, an generates a mock API, as well as the resulting data. Each service should have the ability to be deployed locally as a mock service by any stakeholder, published and shared with other team members as a mock service, and shared as a demonstration of what the service does, or will do. Mock representations of services will minimize builds, the writing of code, and refactoring to accommodate rapid changes during the API development process. Code shouldn’t be generated or crafted until the surface area of an API has been worked out, and reflects the contract that each service will provide.
OpenAPI Documentation Always AVailable In Repository Each microservice should be self-contained, and always documented. Swagger UI, Redoc, and other API documentation generated from OpenAPI has changed how we deliver API documentation. OpenAPI generated documentation should be available by default within each service’s repository, linked from the README, and readily available for running using static website solutions like Github Pages, or available running locally through the localhost. API documentation isn’t just for the microservices owner / steward to use, it is meant for other stakeholders, and potential consumers. API documentation for a service should be always on, always available, and not something that needs to be generated, built, or deployed. API documentation is a default tool that should be present for EVERY microservice, and treated as a first class citizen as part of its evolution.
Bringing An API To Life Using It’s OpenAPI Contract Once an OpenAPI contract has been been defined, designed, and iterated upon by service owner / steward, as well as a handful of potential consumers and clients, it is ready for development. A finished (enough) OpenAPI can be used to generate server side code using a popular language framework, build out as part of an API gateway solution, or common proxy services and tooling. In some cases the resulting build will be a finished API ready for use, but most of the time it will take some further connecting, refinement, and polishing before it is a production ready API. Regardless, there is no reason for an API to be developed, generated, or built, until the OpenAPI contract is ready, providing the required business value each microservice is being designed to deliver. Writing code, when an API will change is an inefficient use of time, in a virtualized API design lifecycle.
OpenAPI-Driven Monitoring, Testing, and Performance A read-to-go OpenAPI contract can be used to generate API tests, monitors, and deliver performance tests to ensure that services are meeting their business service level agreements. The details of the OpenAPI contract become the assertions of each test, which can be executed against an API on a regular basis to measure not just the overall availability of an API, but whether or not it is actually meeting specific, granular business use cases articulated within the OpenAPI contract. Every detail of the OpenAPI becomes the contract for ensuring each microservice is doing what has been promised, and something that can be articulated and shared with humans via documentation, as well as programmatically by other systems, services, and tooling employed to monitor and test accordingly to a wider strategy.
Empowering Security To Be Directed By The OpenAPI Contract An OpenAPI provides the entire details of the surface area of an API. In addition to being used to generate tests, monitors, and performance checks, it can be used to inform security scanning, fuzzing, and other vital security practices. There are a growing number of services and tooling emerging that allow for building models, policies, and executing security audits based upon OpenAPI contracts. Taking the paths, parameters, definitions, security, and authentication and using them as actionable details for ensuring security across not just an individual service, but potentially hundreds, or thousands of services being developed across many different teams. OpenAPI quickly is becoming not just the technical and business contract, but also the political contract for how you do business on web in a secure way.
OpenAPI Provides API Discovery By Default An OpenAPI describes the entire surface area for the request and response of each API, providing 100% coverage for all interfaces a services will possess. While this OpenAPI definition will be generated mocks, code, documentation, testing, monitoring, security, and serving other stops along the lifecycle, it provides much needed discovery across groups, and by consumers. Anytime a new application is being developed, teams can search across the team Github, Gitlab, Bitbucket, or Team Foundation Server (TFS), and see what services already exist before they begin planning any new services. Service catalogs, directories, search engines, and other discovery mechanisms can use OpenAPIs across services to index, and make them available to other systems, applications, and most importantly to other humans who are looking for services that will help them solve problems.
OpenAPI Deliver The Integration Contract For Client OpenAPI definitions can be imported in Postman, Stoplight, and other API design, development, and client tooling, allowing for quick setup of environment, and collaborating with integration across teams. OpenAPIs are also used to generate SDKs, and deploy them using existing continuous integration (CI) pipelines by companies like APIMATIC. OpenAPIs deliver the client contract we need to just learn about an API, get to work developing a new web or mobile application, or manage updates and version changes as part of our existing CI pipelines. OpenAPIs deliver the integration contract needed for all levels of clients, helping teams go from discovery to integration with as little friction as possible. Without this contract in place, on-boarding with one service is time consuming, and doing it across tens, or hundreds of services becomes impossible.
OpenAPI Delivers Governance At Scale Across Teams Delivering consistent APIs within a single team takes discipline. Delivering consistent APIs across many teams takes governance. OpenAPI provides the building blocks to ensure APIs are defined, designed, mocked, deployed, documented, tested, monitored, perform, secured, discovered, and integrated with consistently. The OpenAPI contract is an artifact that governs every stop along the lifecycle, and then at scale becomes the measure for how well each service is delivering at scale across not just tens, but hundreds, or thousands of services, spread across many groups. Without the OpenAPI contract API governance is non-existent, and at best extremely cumbersome. The OpenAPI contract is not just top down governance telling what they should be doing, it is the bottom up contract for service owners / stewards who are delivering the quality services on the ground inform governance, and leading efforts across many teams.
I can’t articulate the importance of the OpenAPI contract to each microservice, as well as the overall organizational and project microservice strategy. I know that many folks will dismiss the role that OpenAPI plays, but look at the list of members who govern the specification. Consider that Amazon, Google, and Azure ALL have baked OpenAPI into their microservice delivery services and tooling. OpenAPI isn’t a WSDL. An OpenAPI contract is how you will articulate what your microservice will do from inception to deprecation. Make it a priority, don’t treat it as just an output from your legacy way of producing code. Roll up your sleeves, and spend time editing it by hand, and loading it into 3rd party services to see the contract for your microservice in different ways, through different lenses. Eventually you will begin to see it is much more than just another JSON artifact laying around in your repository.
You hear me say it all the time–if you are selling services and tooling to the API sector, you should have an API. In support of this way of thinking I like to highlight the API service providers I work with who follow this philosophy, and today’s example is from (Postman](https://getpostman.com). If you aren’t familiar with Postman, I recommend getting acquainted. It is an indispensable tool for integrating, consuming, and collaborating around the APIs you depend on, and are developing. Postman is essential to working with APIs in 2018, no matter whether you are developing them, or integrating with 3rd party APIs.
Further amplifying the usefulness of Postman as a client tool, the Postman API reflects the heart of what Postman does as not just a client, but a complete life cycle tool. The Postman API provides five separate APIs, allowing you orchestration your API integration, consumption, and collaboration environment.
- Collections - The /collections endpoint returns a list of all collections that are accessible by you. The list includes your own collections and the collections that you have subscribed to.
- Environments - The /environments endpoint returns a list of all environments that belong to you. The response contains an array of environments’ information containing the name, id, owner and uid of each environment.
- Mocks - This endpoint fetches all the mocks that you have created.
- Monitors - The /monitors endpoint returns a list of all monitors that are accessible by you. The response contains an array of monitors information containing the name, id, owner and uid of each monitor.
- User - The /me endpoint allows you to fetch relevant information pertaining to the API Key being used.
The user, collections, and environments APIs reflect the heart of the Postman API client, where mocks and monitors reflects its move to be a full API life cycle solution. This stack of APIs, and the Postman as a client tool reflects how API development, as well as API operation should be conducted. You should be maintaining collections of APIs that exist within many environments, and you should always be mocking interfaces as you are defining, designing, and developing them. You should then also be monitoring all the APIs you depend–whether or not the APIs are yours. If you depend on APIs, you should be monitoring them.
I’ve long been advocating that someone development an API environment management solution for API developers, providing a single place we can define, store, and share the configuration, keys, and other aspects of integration with the APIs we depend on. The Postman collections and environment APIs is essentially this, plus you get all the added benefits of the services and tooling that already exist as part of the platform. Demonstrating why as an API service provider, you want to be following your own advice and having an API, because you never know when the core of your solution, or even one of the features could potentially become baked into other applications and services, and be the next killer feature developers can’t do without.
Every API should be tested to ensure it delivers what is expected of it. All code being deployed should meet required unit and code tests, but increasingly API testing is adding another layer of assurance to existing build processes, even going so far as halting CI/CD workflows if tests fail. API testing is another area where API definitions are delivering, allowing tests to be built from existing artifacts, and allowing detailed assertions to be associated with tests to add to and evolve the existing definitions.
API testing has grown over the last couple of years to include a variety of open source solutions, as well as cloud service providers. Most of the quality solutions allow you to import your OpenAPI, and automate the testing via APIs. Here are a few of the solutions I recommend considering as you think about how API testing can be introduced into your API operations.
- Runscope - An API testing service that uses OpenAPI for importing and exporting of API tests and assertions.
- Hippie-Swagger - An open source solution for testing your OpenAPI defined APIs.
- Spring Cloud Contract - Spring Cloud Contract is an umbrella project holding solutions that help users in successfully implementing the Consumer Driven Contracts approach.
- Frisby.js - Frisby is a REST API testing framework built on Node.js and Jasmine that makes testing API endpoints easy, fast, and fun.
There are numerous ways to augment API testing on top of your existing testing strategy. More of these providers are integrating with Jenkins and other CI/CD solutions, allowing API testing to deeply integrate with existing pipelines. My recommendation is that the artifacts from these tests and assertions also live alongside OpenAPI and other artifacts and are used as part of the overall definition strategy, widening the meaning of “contract” to apply across all stops along the lifecycle–not just testing.
While API testing may seem like common sense, I’d say that more than 50% of the organizations I’m talking with do not actively test all their APIs. Of the ones that do, I’d say less than half get very granular in their testing or follow test driven development philosophies. This is where service providers like Runscope deliver, helping bring the tools and expertise to the table, allowing you to get up and running in a cloud environment, building on a platform, rather than started from scratch when it comes to your API testing.
I’m evolving forward my thoughts on algorithmic observability and transparency using APIs, and I was recently introduced to TLA+, or the Temporal Logic of Actions. It is the closest I’ve come to what I’m seeing in my head when I think about how we can provide observability into algorithms through existing external outputs (APIs). As I do with all my work here on API I want to process TLA+ as part of my API research, and see how I can layer it in with what I already know.
TLA+ is a formal specification language developed by Leslie Lamport, which can be used to design, model, document, and verify concurrent systems. It has been described as exhaustively-testable pseudocode which can provide a blueprint for software systems. In the context of design and documentation, TLA+ can be viewed as informal technical specifications. However, since TLA+ specifications are written in a formal language of logic and mathematics it can be used to uncover design flaws before system implementation is underway, and are amenable to model checking for finding all possible system behaviours up to some number of execution steps, and examines them for violations. TLA+ specifications use basic set theory to define safety (bad things won’t happen) and temporal logic to define liveness (good things eventually happen).
TLA+ specifications are organized into modules.Although the TLA+ standard is specified in typeset mathematical symbols, existing TLA+ tools use symbol definitions in ASCII, using several terms which require further definition:
- State - an assignment of values to variables
- Behaviour - a sequence of states
- Step - a pair of successive states in a behavior
- Stuttering Step - a step during which variables are unchanged
- Next-State Rlation - a relation describing how variables can change in any step
- State Function - an expression containing variables and constants that is not a next-state relation
- State Predicate - a Boolean-valued state function
- Invariant - a state predicate true in all reachable states
- Temporal Formula - an expression containing statements in temporal logic
TLA+ is concerned with defining the correct system behavior, providing with a set of operators for working through what is going on, as well as working with data structures. There is tooling that has been developed to support TLA+ including an IDE, model checker, and proof system. It is all still substantially over my head, but I get what is going on enough to warrant moving forward, and hopefully absorbing more on the subject. As with most languages and specifications I come across it will just take some playing with, and absorbing the concepts at play, before things will come into focus.
I’m going to pick up some of my previous work around behavior driven assertions, and how assertions can be though of in terms of the business contracts APIs put forward, and see where TLA+ fits in. It’s all still fuzzy, but API assertions and TLA+ feels like where I want to go with this. I’m thinking about how we can wrap algorithms in APIs, write assertions for them, and validate across the entire surface area of an algorithm, or stack of API exposed algorithms using TLA+. Maybe I’m barking up the wrong tree, but if nothing else it will get me thinking more about this side of my API research, which will push forward my thoughts on algorithmic transparency, and audit-able observability.
I’m needing data for use in human service API implementations. I need sample organizations, locations, and services to round off implementations, making it easier to understand what is possible with an API, when you are playing with one of my demos.
There are a number of features that require there to be data in these systems, and is always more convincing when it has intuitive, recognizable entries, not just test names, or possibly latin filler text. I need a variety of samples, in many different categories, with a complete phone, address, and other specific data points. I also need this across many different APIs, and ideally, on demand when I set up a new demo instance of the human services API.
It is kind of a poor man’s way of creating test data, then publishing to Github for use in a variety of continuous integration workflows. I can maintain a rich folder of test data sets for a variety of use cases in spreadsheets, and even invite other folks to help me create and manage the data stored in spreadsheets. Then I can publish to a variety of Github repositories as YAML, and integrated into any workflow, loading test data sets into new APIs, and existing APIs as part of testing, monitoring, or even just to make an API seem convincing.
To support my work I have a spreadsheet published, and two scripts, one for pulling organizations, and the other for pulling locations–both which publish YAML to the _data folder in the repository. I’ll keep playing with ways of publishing test data year, for use across my projects. With each addition, I will try and add a story to this research, to help others understand how it all works. I am hoping that I will eventually develop a pretty robust set of tools for working with test data in APIs, as part of a test data continuous publishing and integration cycle.
The Runscope team recently published a post on a pretty cool approach to using Google Sheets for running API tests with multiple variable sets, which I thought is valuable at a couple of levels. They provide a template Google Sheet for anyone to follow, where you can plug in your variable, as well as your Runscope API Key, which allows you to define the dimensions of the tests you wish to push to Runscope via their own API.
The first thing that grabs me about this approach is how Runscope is allowing their customers to define and expand the dimensions of how they test their API using Runscope in a way that will speak to a wider audience, beyond just the usual API developer audience. Doing this in a spreadsheet allows Runscope customers to customize their API tests for exactly the scenarios they need, without Runscope having to customize and respond to each individual customer's needs--providing a nice balance.
The second thing that interests me about their approach is the usage of a Googe Sheet as a template for making API calls, whether you are testing your APIs, or any other scenario an API enables. This type of templating of API calls opens up the API client to a much wider audience, making integration copy and pastable, shareable, collaborative, and something anyone can reverse engineer and learn about the surface area of an API--in this scenario, it just happens to be the surface area of Runscope's API testing API.Â
Runscope's approach is alignment with my previous post about sharing data validation examples. A set of assertions could be defined within a spreadsheetsÂ and any stakeholder could use the spreadsheet to executeÂ and make sure the assertions are met. This would have huge implications for the average business user to help make sure API contracts are meeting business objectives. I'm considering using this approach to empower cities, counties, and states to test and validate human services API implementations as part of my Open Referral work.
It told John Sheehan, the CEO of Runscope that their approach was pretty creative, and he said thatÂ "Google sheets scripts are underrated" and that Google Sheets is the "API client for the everyperson". I agree. I'd like to see more spreadsheet templates like this used across the API life cycle when it comes to design, deployment, management, testing, monitoring, and every other area of API operations. I'd also like to see more spreadsheet templates available for making calls to other common APIs, making APIs accessible to a much wider audience, who are familiar with spreadsheets, and more likely to be closer to the actual problems in which API solutions are designed to solve.
I was studying examples of how I can validate the data returned from a human services APIs demo, and develop a set of API tests, as well as API service providers who can implement the tests, for cities to consider as part of their API deployments that are serving up locations and organizations where you can find critical services. I'm looking for examples of the common things like API availability and response time, but I'm also looking to get very granular and specialized to organizational, location, and service APIs.
The image I borrowed from RunScope helps visualize what I'm talking about, showing us how we can keep an eye on the basics, but also getting really granular when specifying what we expect from of our APIs. I have a pretty good imagination when it comes to thinking of scenarios I want to test for, but I'm also looking for any API providers who might be already sharing their tests and being more transparent when it comes to their API monitoring and testing practices. If you know of any API providers that would be willing to share the lists of what types of things they test for, I'd love to hear more.
I'm thinking a regular blog series on different examples of how people are testing APIs from a diverse range of business sectors might help stimulate people's imagination when it comes to API testing concepts. I'm thinking it is another area that we could all learn a lot from each other if there was just a little bit of sharing. I'd love it if the examples were machine readable and reusable in any API testing service, but I would settle for just a blog post, or sharing of a bulleted list of API tests via email, or another channel. ;-)
I was going through Chai, a behavior, and test driven assertion library, and spending some time learning about behavior driven development, or BDD, as it applies to APIs today. This is one of the topics I've read about and listened to talks from people I look up to, but just haven't had the time to invest too many cycles in learning more. As I do with other interesting, and applicable areas, I'm going to add as a research area, which will force me to bump it up in priority.
In short, BDD is how you test to make sure an API is doing what is expected of it. It is how the smart API providers are testing their APIs, during development, and production to make sure they are delivering on their contract. Doing what I do, I started going through the leading approaches to BDD with APIs, and came up with these solutions:
- Nightwatch.js - Nightwatch.js is an easy to use Node.js based End-to-End (E2E) testing solution for browser based apps and websites.
- Fluent Assertions - Fluent Assertions is a set of .NET extension methods that allow you to more naturally specify the expected outcome of a TDD or BDD-style test.
- Vows - Asynchronous behaviour driven development for Node.
- Unexpectd - The extensible BDD assertion toolkit
If you know of any that I'm missing, please let me know. I will establish a research project, add them to it, and get to work monitoring what they are up to, and better track on the finer aspects of BDD. As I was searching on the topic I also came across these references that I think are worth noting, because they are from existing providers I'm already tracking on.
- Runscope - Discussing BDD using Runscope API monitoring.
- Postman - Discussing BDD using Postman API client.
I am just getting going with this area, but it is something I'm feeling goes well beyond just testing and touches on many of the business and political aspects of API operations I am most concerned with. I'm looking to provide ways to verify an API does what it is supposed to, as well as making sure an API sizes up to claims made by developers or the provider. I'm also on the hunt for any sort of definition format that can be applied across many different providers--something I could include as part of APIs.json indexes and OpenAPI Specs.
Earlier I had written on the API assertions we make, believe in, and require for our business contracts. This is an area I'm looking to expand on with this API assertion research. I am also looking to include BDD as part of my thoughts on algorithmic transparency, exploring how BDD assertions can be used to validate the algorithms that are guiding more of our personal and business worlds. It's an interesting area that I know many of my friends have been talking about for a while but is now something I want to work to help normalize for the rest of us who might not be immersed in the world of API testing.
To Incentivize API Performance, Load, And Security Testing, Providers Should Reduce Bandwidth And Compute Costs Asscociated03 Nov 2015
I love that AWS is baking monitoring testing by default in the new Amazon API Gateway. I am also seeing new service from AWS, and Google providing security and testing services for your APIs, and other infrastructure. It just makes sense for cloud platforms to incentivize security of their platforms, but also ensure wider success through the performance and load testing of APIs as well.
As I'm reading through recent releases, and posts, I'm thinking about the growth in monitoring, testing, and performance services targeting APIs, and the convergence with a growth in the number of approaches to API virtualization, and what containers are doing to the API space. I feel like Amazon baking in monitoring and testing into API deployment and management because it is in their best interest, but is also something I think providers could go even further when it comes to investment in this area.
What if you could establish a stage of your operations, such as QA, or maybe production testing, and the compute and bandwidth costs associated with operations in these stages were significantly discounted? Kind of like the difference in storage levels between Amazon S3 and Glacier, but designed specifically to encourage monitoring, testing, and performance on API deployments.
Maybe AWS is already doing this and I've missed it. Regardless it seems like an interesting way that any API service provider could encourage customers to deliver better quality APIs, as well as help give a boost to the overall API testing, monitoring, and performance layer of the sector. #JustAThought
The New Mind Control APIs That Salesforce Is Testing On Conference Attendees Is Available To Premier Partners14 Sep 2015
The Dreamforce conference is happening this week in San Francisco, a flagship event for the Platform as a Service (PaaS) company. Salesforce is one of the original pioneers in API technology, allowing companies to empower their sales force, using the the latest in technology. Something that in 2015, Salesforce is taking this to the next level, with a handful of attendees, and partners in attendance at the conference.
Using smart pillow technology, Salesforce will be testing out a new set of subliminal mind control APIs. All attendees of the Dreamforce conference have agreed to be part of the tests, through their acceptance of the event terms of service, but only a small group of 500 individuals will actually be targeted. Exactly which attendees are selected will be a secret, even from the handful of 25 partners who will be involved in the test.
Through carefully placed hotel pillows, targeted attendees will receive subliminal messages, transmitted via smart pillow APIs developed by Salesforce. Messages will be crafted in association with partners, testing out concepts of directing attendees what they will eat the next day, which sessions they are attending, where they will be going in the exhibit hall, and who they will be networking with The objective is to better understand how open the conference attendees are open to suggestion, in an conference environment.
While some partners of this mind control trial are just doing random tests to see if the technology works, others are looking to implement tasks that are in sync with their sales objectives. Ernst Stavro Blofeld, CEO of Next Generation Staffing Inc, says "the Salesforce test represents the future of industry, and the workforce--this weeks test is about seeing what we can accomplish at a conference, but represents what we will be able to achieve in our workforce on a daily basis."
Salesforce reminded us that this is just a simple test, but an important one that reflects the influence the company already has over its constituents. The company enjoys one of the most loyal base of business users, out of all leading software companies in the world, and this new approach to targeting a loyal base of users, is just the beginning of a new generation of API engineered influence.
This is my testing.
I'm preparing for a talk at the The Smart Grid Interoperability Panel Second Annual Conference, in Nashville Tennessee, specifically participating on a panel titled "Using Power Grid Open Data Initiatives". I accepted the request to go speak as part of my wider work on the Green Button iniative out of The White House, DOE, NIST, and the GSA. I was asked to provide some thoughts on how to help move the Green Button efforts forward earlier this winter, and again in the spring, and just haven't had the bandwidth to give any energy, so I saw this as a great opportunity to make some time as part of this panel.
In May, The White House, 18F, some Presidential Innovation Fellows, and myself were asked to move the Green Button ball forward, resulting in a new website, and developer area that is all hosted on Github. I'm bummed I wasn't able to make time to participate, but now I have been able to go through the new site, and developer area, and gather my thoughts on where we could go next with the effort.
Before we get started, lets start with the basics, what is Green Button? Nick Sinai (@NickSinai), Deputy Chief Technology Officer of the United States, puts it this way:
Green Button is a policy idea. It's the notion that customers – residential, commercial, industrial, and yes, government customers of energy – ought to get access to their own energy data, in a standard digital format. The Administration has articulated this several times, in a number of Administration energy, climate, and smart grid policy documents. The government is a big customer of energy, and we deserve our own energy usage and price data.
Green Button is also a public-private initiative, in response to a 2011 White House call to action. The White House, DOE, NIST, and GSA have been collaborating with the utility and tech industries on this growing effort for a few years now. The White House has been convening industry and celebrating its progress. NIST has been supporting industry on development of the standard, DOE has been working with utilities, and GSA has been an early adopter.
Finally, Green Button is an actual data standard, for formatting and transferring energy usage and price data. This standard can be implemented in both utility and non-utility contexts. Customers can manually download or upload a file formatted in the standard, and IT systems can automatically transfer data between them using the standard.
The White House, 18F, and fellow PIFs, have done a great job organizing everything under a single, Github pages site, at greenbuttondata.org. The site is a big improvement over what was there before, and moves us closer to solving the fragmentation in the Green Button effort, which I believe is the fundamental issue that is holding it back from being fully realized. Green Button is a big vision, and it is going to take some serious effort to bring together all of the industry, and 3rd party efforts, and most importantly getting individual consumers on-board with taking control over their own energy data.
To help organize my thoughts on how we can move Green Button forward, something I will be discussing on stage in Nashville, I wanted to walk through the site, and take a snapshot of where we are at, then work on a strategy for what is needed to keep the momentum we already have moving forward. Green Button is an extremely critical effort in not just empowering individuals and institutions to take control over their energy data, but also for the overall health of the energy sector, and whether the utility companies can see it or not, open data and APIs will be central to their continued success. So as I do with other areas, let's walk through where we are at currently with Green Button, to help prime the discussion about where we should go.
When you land on the greenbuttondata.org site, it looks like a modern, clean website effort, with a simple tagline and meaningful image to help you understand what Green Button is all about. The first description is "Helping You Find and Use Your Energy Data", and then when you scroll down you see an answer to the question What is Green Button? -- "Green Button is a secure way to get your energy usage information electronically. I like the concise messaging, but it is solely focused on the consumer, and leaves out the commercial energy users, public institutions, utilities & energy service providers, 3rd party software vendors, and energy efficiency organizations listed on the "use" page. I know this all revolves around energy data, but when you land on site, you should have the site speak to you, no matter who you are.
I think the "use" page does a great job in breaking down who the target audience is, but the first impression doesn't reflect this, and I don't think there is any path for these users to follow, once you do find yourself on greenbuttondata.org. As a data custodian, or 3rd party developer, I think the build or developer page will quickly speak to you, but as a consumer, you are quickly dropped from the focus of the site and will be completely lost in the rich information that is available. To on-board each user properly, we will need to begin to carve out paths for each user, one that start with a meaningful first impression off of the home page, then puts them on a path that leads them twoard action and the relevant resources they will need, depending on their role.
Learn About Green Button
I really like the learn page for Green Button. It is clean, simple, informative, and not overwhelming for me to learn about what Green Button is, from any perspectives. My only suggestions for next steps is that we begin massaging some of the rich content available under "library", and link to specific learning opportunities from this page. Each summary should provide users with links to follow, taking them to the detail they will need to fully understand each aspect of Green Button as it pertains to their position. However, with that said it is critical to keep this page a simple overview of Green Button, and make it an easy doorway to the world of energy data.
Using Green Button
As I said above, the "use" section provides a nice overview of who should be using Green Button, with sections focusing on commercial energy users, public institutions, utilities & energy service providers, 3rd party software vendors, and energy efficiency organizations, as well residential consumers. What is needed for each of these sections, is a clear call to action, taking you to another page that is a "getting started" specifically targeting your role in the Green Button movement. I don't think the lack of this, is a deficiency of what is currently there, it is just the next logical step for evolving this page to better onboard users, now that these roles are better defined.
The Green Button Community
This is the first time I've seen the Green Button community reflected on a single page like this, and is exactly what is needed to help reduce the fragmentation currently present across the community. Presenting the four groups in this way, complete with links to their sites, and relevant contact information to get involved, is very important for bringing together the community. My only critique is that the page could use a little more layout love, formatting, logos, and some polish to keep it looking as good as the rest of the site—nothing major. Eventually it would also be nice to have some sort of stream of activity across all of these efforts, aggregated here. I'm not sure how this would occur, as the groups are all using different ways to keep members informed, but something should be considered, further bringing together the community.
Build With Green Button
The developers section probably needs the most help right now, and I'm not 100% sure of how to make more coherent. It is a little redundant and circular, and its called "build" on home page, and "developers" in the top navigation, something that should be consistent. The RESTful APIs is represented twice, and i see glimpses of trying to provide separate information for data stewards, and 3rd party developers. Along with the development of specific paths for different target users, this needs to be reworked, and woven into those efforts, but I do like the focus on the open source nature of Green Button. The first time I landed on Green Button, I didn't fully grasp that it was an open source API that anyone can deploy, and that the sandbox version that is in operation is just a demo, something that I think we need to make fully clear to users of all types.
We have a big challenge ahead when it comes to helping data custodians understand what is possible, and hopefully we can help spur 3rd party developers in not just build around existing Green Button code, but also work to develop new versions in other languages, as well as specific cloud offerings on maybe Amazon or Heroku. The sky is the limit when it comes to developing, and building Green Button solutions, both server and client side, and we need to make the separation as clear as possible. It will take some serious architectural vision to help bridge what code is currently available for Green Button, and stimulate commercial energy users, public institutions, utilities & energy service providers, 3rd party software vendors, and energy efficiency organizations in understanding what is possible, and incentivize them to deliver solutions that are quickly deployable across the cloud landscape.
Green Button Library
As with the "learn" and "use" sections of the site, the current library section was a great step forward in bringing together the wealth of current resources available to support Green Button efforts. What is needed now is just the refinement of what is there, making it easier to access, and learn from, while also making sure that resources are appropriately grouped into buckets targeting each of the Green Button user groups. As I'm working through the the library of materials, I can see there are some seriously rich resource available, but there is a lot of disconnect between them because they are designed, developed and deployed to support different goals, by different authors—we need to establish some consistency between them.
Right now the library is very much a list of resources, and it would be nice to make sure it truly is a library that is organized, indexable, and is easy to navigate. Having all of these resources in a single location is an excellent start, but how do we start refining them, and making them much more usable by all users? Documents should have a consistent document formats, videos should have single Youtube (or other) channel, and much more. All of this would make it much more likely that these resources would be explored, an consumed by a wider audience, beyond just the alpha geek crowd.
Green Button Testing Tools
I'm happy to see the Green Button testing tool here, but ultimately it feels like one tool, that should be in a toolbox. Right now it is its own top level navigation item, and I don't think a single tool should be elevated to this level. I would change this to tools, and make the testing tool the one item in the toolbox right now, and I'm sure there are others we can quickly add to the toolbox as well. As with other areas, we should break down the toolbox by user group, making sure consumers easily find what they need, as well as utility providers, 3rd party developers and the other user groups.
Getting Started With Green Button
I was excited to see the Getting Started button, until I realized it was just an email address. ;-( That isn't getting started, it is sending an email. Getting started should be prominent, and truly provide users with easy paths to well...get started. If you are data custodian, utility, or energy provider, you should have a simple page that explains how to get started, in a self-service way—no email needed. Separately, there should be contact information for Green Button, something that hopefully includes much more than just an email address, with no face and personality behind it.
Acknowledging Where We Are
That is a quick walkthrough of where things are at with greenbuttondata.org, and in my opinion, things have come a long ways from what I was seeing spread across the Green Button landscape this last winter. Most importantly it is aggregating the community, developer, and the wealth of other resources into a library, which is a very critical step to continue moving Green Button forward. In my opinion the v1 tech of Green Button tech is in place, it is just lacking all the refinement, storytelling, and relationship building that is necessary to move Green Button into the consciousness of utility companies, 3rd party developers, and the average, everyday energy consumer—so how do we do this?
Green Button Needs A Champion
First, before we get into any of the nuts and bolts of what we can do to keep greenbuttondata.org rolling forward, the project is going to need a champion. I think The White House, DOE, NIST, and GSA are doing an amazing job of making sure things move forward, but greenbuttondata.org needs someone who is super passionate about energy data, APIs, understands the energy industry, and wants to put in the hours necessary to refine the information currently available, build relationships, and generate new content that will bring in new players. This role isn't some cushy job that you will get a regular paycheck for, but for the right person, I think it could be pretty lucrative, if you get creative in piecing together sponsorship and support from industry players, organizations, and worked hard on the grant writing front. Essentially you need The API Evangelist, for energy data and APIs.
Who's offering Green Button?
I think the first place to start is visible right on the home page, and looking at who is already putting Green Button data to work. I see 50+ entities who are already putting Green Button to work, so who are these people, and how can we showcase what they are up to. There are some meaningful implementations here, and I know there is some great material here to demonstrate the power, and importance of Green Button, and help spark the imagination of new visitors. Green Button has traction, the problem is not enough people know about it, or have the imagination to understand how it is being used. Let's take the time to showcase this, and create some really great content that will make the site more educational. This is something that can be led by the Green Button evangelist I talk about above, but is also something I think the community should also contribute to. I'm going to carve out some time to reach out to some of the providers listed, and see if i can showcase how they are putting Green Button to work, and generate more detail, and content that can be contributed to greenbuttondata.org. Do you want to help?
Showcase Of How Green Button Is Used
Building on the work above, we need a place to showcase how Green Button is being put to use. I'm not sure this should be a top level navigation item, but if we group each entry in the showcase, by the type of user, I think we can make it one stop of the path each user takes, as they learn about Green Button. As each commercial energy users, public institutions, utilities & energy service providers, 3rd party software vendors, and energy efficiency organizations, and individual energy users is learning about Green Button, they should also be exposed to examples of other similar individuals or companies like them that are already putting Green Button to work. This will go a long way in helping people see the potential of Green Button, and begin the journey of putting it to work across the energy industry landscape in new ways.
Blog For Bringing Green Button To Life
The greenbuttondata.org site needs a blog. This is something that will be difficult without a champion to keep alive, but a blog is going to be essential in bringing the site to life, helping share stories about the value Green Button is bringing to companies, organizations, institutions, and most importantly the average consumer. Without a blog, any developer community will not have a soul, or a personality, and it will be difficult to convince anyone that someone is home, and that they should trust and care about Green Button. I think a blog could easily be crowdsourced, allowing passionate folks like myself to post, as well as other organizations, companies, and key stakeholders to post relevant stories, that will give the site a heartbeat. A blog will be central to any of the suggestions I will have to help move things forward, and give greenbuttondata.org a personality that will go a long way in building trust amongst users, and across the industry.
Giving Some Coherence To The Developers Section
The developer section of greenbuttondata.org will be essential to scaling the effort, and right now the page is a little all over the place, and will take some significant effort to simplify, make usable, and bring the wealth of developer resources into focus. This will take some serious work, by someone who is a developer, architect, and can make actually organize everything into something that easily on-boards data custodians, and 3rd party developers with as little friction as possible. You have to walk them through the wealth of tooling that is already available, show them what is possible, and then give them the downloads they need to get things working in their world.
There is also a need for some other additional tooling, some of the current solutions are very enterprise oriented, and I think with some encouragement, providers could replicate Green Button tooling in other languages like Node.js, Python, PHP, and other platforms that will encourage rapid adoption by other providers. There also needs to be some ways to help people quickly bring Green Button to life using cloud platforms like AWS, Heroku, Google, Azure and other platforms that companies and individuals are already depending on.
The developer section is something that will take some deep thinking, hacking, and architectural magic from the champion, and Green Button evangelist. They will have to look at it through the eyes of each of the data custodians, and 3rd party developers who are already putting Green Button to use, and try to deliver things in a way that will speak to this, as well as potentially other new users. This type of work is not easy, and takes some serious effort, something you can't expect to happen overnight. However, if it is done right this can really help scale the number of Green Button implementations in the wild, and take things to the next level much quicker.
Turning The Library Into A Consistent Resource
I am happy to see all of the rich Green Button resources brought into a single location, but I wouldn't call it quite a library yet. It is a listing of valuable resources, that aren't really organized in a way that speaks to the different Green Button users, and are not consistent in form because they come from different sources. Even with this said, their is a wealth of resources available there, and with some work you could build a really nice, interactive library that can help educate users on how to put Green Button to work. Similar to the showcase, once the library is organized, and grouped by target user, I think the library can be a stop on the path that each user takes, showing them exactly the resources they need in the library to help onboard them properly.
Establishing Paths For Green Button Users
As I discussed above, each user needs a path they can take from the "use" page to begin their journey. Right now the "use" page is a dead end, where it should actually be a call to action, providing each visitor the chance to take a path through the site that speaks to them, without forcing them to have to wade through the wealth of resources that are currently there. From the "use" page, each user can be taken to a showcase of other implementations from similar users, then depending on their role, could be walk through other sections of the site, landing in the library, presenting with exactly what they need to get going. I'm not exactly sure what the user experience will be on these new paths, but I think once we profile the existing uses of Green Button, and unwind the developer and library resources, a pretty orderly route can be established for each user group. These paths will go a long way to onboard users in a fraction of the time, and maximize the potential reach, and scale of the platform—adding more implementations to the Green Button platform, and scaling the audience with each new user.
Taking Green Button From Site to Community
I will stop here. I think this is all that should be focused on for now, when it comes to moving Green Button forward. It is important to not bite off too much, and make sure we can be successful in moving things forward, and not make things more complex. The goal is to simplify what we have, now that we have everything organized into a single site, and begin the process of bringing greenbuttondata.org to life. With someone at the helm, an active blog, and a more coherent focus on each user group, I think that things will start picking up steam, and with more outreach, and involvement with existing Green Button implementations, and the existing Green Button community, we can move greenbuttondata.org from being just a site, and put it on its way to becoming a community.
It is important that Green Button evolves to become a community. It cannot remain just a government initiative. Green Button has to be a vibrant community that commercial energy users, public institutions, utilities & energy service providers, 3rd party software vendors, energy efficiency organizations, and individual energy users are all part of, otherwise it will always remain just something being pushed from the top down. Green Button has to be also owned by the individual energy users, and institutions, providing essential bottom up momentum to match the energy given from the top by the federal government partners—without this the energy industry will never buy in.
Profiling the existing Green Button implementations, and making the site speak to each of the user groups will be important for taking things to the next step. This process will help communicate to a next generation of implementations what is possible, and through regular showcasing and storytelling we can move Green Button beyond just a policy idea, and initiative from government, or just a technical data standard, and transform it into something that is a default part of the energy industry. In this new world, energy users will be used to having control over their data, and entirely new markets will be established delivering services to energy consumers, within this new space.
All the parts and pieces are there, and much like last round of work on the greenbuttondata.org site brought all these resources together, we need to figure out how to bring the energy industry together and show them the potential of Green Button data and APIs. We need to make sure energy consumers, both individual and institutional, understand the importance of having control over their energy data, and show data custodians that this is the future of doing business in the energy space. Once we can achieve this, Green Button will take on a life of its own, driven not just by the government, or even the utility providers, but by the energy of 3rd party companies who are delivering meaningful solutions for institutional, organizational, and individual energy consumers.
I am continuing my research into how universities are using APIs, and while I was going through the developer areas for the universities I track on, I noticed an interesting mobile developer toolkit, from University of Michigan.
When you land on the homepage of the University of Michigan developer portal, to the right you will see some valuable resources that is looking to help developers think through the bigger picture of designing, developing, deploying, testing and distributing, mobile application that are built on campus resources.
The University of Michigan mobile developer toolkit is broken down into four separate groups:
Develop & Test
- Choosing a platform
- Multi-device development
- Integrating Single Sign-On or CoSign
- U-M (APIs)
- Using Emulators and Simulators
- Testing Your App
I think the resources they provide, represent a very long term vision around delivering API resources to developers, who will be building applications for the institution--something that all universities should look at emulating.
You want developers, who are building mobile applications on top of campus API resources to be successful, so providing them with the education, training and resources they need to deliver, is critical.
I also think it is cool, that at the bottom of the mobile developer toolkit, they provide two other links:
They want their app developers to socialize with other campus application developers, and be aware of opportunities to compete in hackathons and other competitions--on and off campus.
Developing mobile applications is the number one incentive for universities to deploy APIs, and jumpstart their API efforts like at BYU, UW and UC Berkeley, and it just makes sense to provide a mobile developer toolkit for developers. Education around APIs and mobile application development is critical to the success of any API initiative, but even more so, when it occurs across a large institution, by a variety of internal and external groups.
I’ll add the mobile developer toolkit to my list common building blocks for not just university APIs, but all API initiatives.
Contributing To The Testing & Monitoring Lifecycle
When it comes to testing, and monitoring an API, you begin to really see how machine readable API definitions can be the truth, in the contract between API provider and consumer. API definitions are being used by API testing and monitoring services like SmartBear, providing a central set of rules that can ensure your APIs deliver as promised.
Making sure all your APIs operate as expected, and just like generating up to date documentation, you can ensure the entire surface area of your API is tested, and operating as intended. Test driven development (TDD) is becoming common practice for API development, and API definitions will play an increasing role in this side of API operations.
An API definition provides a central truth, that can be used by API providers to monitor API operations, but also give the same set of rules to external API monitoring services, as well as individual API consumers. Monitoring, and understanding an API up time, from multiple external sources is becoming a part of how the API economy is stabilizing itself, and API definitions provide a portable template, that can be used across all API monitoring services.
Testing and monitoring of vital resources that applications depend on is becoming the norm, with new service providers emerging to assist in this area, and large technology companies like Google, making testing and monitoring default in all platform operations. Without a set of instructions that describe the API surface area, it will be cumbersome, and costly, to generate the automated testing and monitoring jobs necessary to produce a stable, API economy.
I’ve been thinking a lot about API design lately, the services and tooling coming from Apiary, RAML and Swagger, and wanted to explore some thoughts around what I would consider to be killer features for the killer API design editor. Some of these thoughts are derived from the features I’ve seen in Apiary and RAML editor, and most recently the Swagger Editor, but I’d like to *riff* on a little bit and play with what could be the next generation of features.
While exploring my dream API design editor, I’d like to walk through each group of features, organized around my indentations and objectives around my API designs.
When kicking off the API design process, I want to be able to jumpstart the API design lifecycle from multiple sources. There will be many times that I want to start from a clean slate, but many times I will be working from existing patterns.
- Blank Canvas - I want to start with a blank canvas, no patterns to follow today, I’m painting my masterpiece.
- Import Existing File - I have a loose API design file laying around, and I want to be able to open, import and get to work with it, in any of the formats.
- Fork From Gallery - I want to fork one of my existing API designs, that I have stored in my API design taller (I will outline below).
- Import From API Commons - Select an existing API design pattern from API Commons and import into editor, and API design gallery.
My goals in getting started with API design, will be centered around re-use the best patterns across the API space, as well as my own individual or company API design gallery. We are already mimicking much of this behavior, we just don’t have a central API design editor for managing these flows.
Editing My API Design
Now we get to the meat of the post, the editor. I have several things in mind when I’m actually editing a single API definition, functions I want, actions I want to take around my API design. These are just a handful of the editor specific features I’d love to see in my perfect API design editor.
- Multi-Lingual - I want my editor to word with API definitions in API Blueprint, RAML and Swagger. I prefer to edit my API designs in JSON, but I know many people I work with will prefer markdown or YAML based, and my editor needs to support fluid editing between all popular formats.
- Internationalization - How will I deal with making my API resources available to developers around the world? Beyond API definition langugages, how do I actually make my interfaces accessible, and understood by consuers around the glob.e
- Dictionary - I will outline my thoughts around a central dictionary below, but I want my editor to pull from a common dictionary, providing a standardized language that I work from, as well as my company when designing interfaces, data models, etc.
- Annotation - I want to be able to annotate various aspects of my API designs and have associated notes, conversation around these elements of my design.
- Highlight - Built in highlighting would be good to support annotations, but also just reference various layers of my API designs to highlighting during conversations with others, or even allowing the reverse engineer of my designs, complete with the notes and layers of the onions for others to follow.
- Source View - A view of my API design that allows me to see the underlying markdown, YAML, or JSON and directly edit the underlying API definition language.
- GUI View - A visual view of my API design, allowing for adding, editing and removing elements in an easy GUI interface, no source view necessary for designing APIs.
- Interactive View - A rendered visual view of my API, allowing me to play with either my live API or generated mock API, through interactive documentation within my editors.
- Save To Gallery - When I’m done working with my API designs, all roads lead to saving it to my gallery, once saved to my working space I can decide to take other actions.
- Suggestions - I want my editor to suggest the best patterns available to me from private and public sources. I shouldn't ever design my APIs in the dark.
The API design editor should work like most IDE’s we see today, but keep it simple, and reflect extensibility like GIthub’s Atom editor. My editor should give me full control over my API designs, and enable me to take action in many pre-defined or custom ways one could imagine.
My API designs represent the truth of my API, at any point within its lifecycle, from initial conception to deprecation. In my perfect editor I should be able to take meaningful actions around my API designs. For the purposes of this story I’m going to group actions into some meaningful buckets, that reflect the expanding areas of the API lifecycle. You will notice the four areas below, reflect the primary areas I track on via API Evangelist.
Early on in my API lifecycle, while I’m crafting new designs, I will need to take action around my designs. Designs actions will help me iterate on designs before I reach expensive deployment and management phases.
- Mock Interface - With each of my API designs I will need to generate mock interfaces that I can use to play with what my API will deliver. I will also need to share this URL with other stakeholders, so that they can play with, and provide feedback on my API interface.
- Copy / Paste - API designs will evolve and branch out into other areas. I need to be able to copy / paste or fork my API designs, and my editor, and API gallery should keep track of these iterations so I don’t have to. The API space essentially copy and pastes common patterns, we just don’t have a formal way of doing it currently.
- Email Share - I want to easily share my API designs via email with other key stakeholders that will be part of the API lifecycle. Ideally I wouldn’t be emailing around the designs themselves, just pointers to the designs and tools for interacting within the lifecycle.
- Social Share - Sometimes the API design process all occur over common social networks, and in some cases be very public. I want to be able to easily share all my API designs via my most used social networks like Github, Twitter and LinkedIn.
- Collaboration - API design should not be done in isolation, and should be a collaborative process with all key stockholders. I would like to to even have Etherpad style real-time interactions around the design process with other users.
API design actions are the first stop, in the expanding API design lifecycle. Being able to easily generate mocks, share my interfaces and collaborate with other stakeholders. Allowing me to quickly, seamlessly take action throughout the early design cycles will save me money, time and resources early on—something that only become more costly and restrictive later on in the lifecycle.
Next station in the API design lifecycle, is being able to deploy APIs from my designs. Each of the existing API definition formats provide API deployment solutions, and with the evolution in cloud computing, we are seeing even more complete, modular ways to take action around your API designs.
- Server - With each of my API designs, I should be able to generate server side code in the languages that I use most. I should be able to register specific frameworks, languages, and other defining aspects of my API server code, then generate the code and make available for download, or publish using Github and FTP.
- Container - Cloud computing has matured, producing a new way of deploying very modular architectural resources, giving rise to a new cloud movement, being called containers. Container virtualization will do for APIs, what APIs have done for companies in the last 14 years. Containers provide a very defined, self-contained way of deploying APIs from API design blueprints, ushering a new ay of deploy API resources in coming years.
I need help to deploy my APIs, and with container solutions like Docker, I should have predefined packages I can configure with my API designs, and deploy using popular container solutions from Google, Amazon, or other coud provider.
After I deploy an API I will need to use my API definitions as a guide for an increasing number of areas of my management process, not just the technical, but the business and politics of my API operations.
- Documentation - Generating of interactive API documentation is what kicked off the popularity of API design, and importance of API definitions. Swagger provider the Swagger UI, and interactive, hands-on way of learning about what an API offered, but this wasn’t the only motivation—providing up to date documentation as well, added just the incentives API providers needed to generate machine readable documentation.
- Code - Second to API documentation, providing code samples, libraries, and SDKS is one of the best ways you can eliminate friction when on boarding new API users. API definitions provide a machine readable set of instructions, for generating the code that is necessary throughout the API management portion of the API lifecycle.
I predict, with the increased adoption of machine readable API formats like API Blueprint, RAML and Swagger, we will see more layers of the API management process be expanded on, further automating how we manage APis.
Having your APIs found, and being able to find the right API design for integration, are two sides of an essential coin in the API lifecycle. We are just now beginning to get a handle on what is need when it comes to API discovery.
- APIs.json - I should be able to organize API designs into groupings, and publish an APIs.json file for these groups. API designs should be able to be organized in multiple groups, organized by domain and sub-domain.
- API Commons - Thanks to Oracle, the copyright of API of API definitions will be part of the API lifecycle. I want the ability to manage and publish all of my designs to the API Commons, or any other commons for sharing of API designs.
The discovery of APIs has long been a problem, but is just now reaching the critical point where we have to start develop solutions for not just finding APIs, but also understanding what they offer, and the details of of the interface, so we can make sense of not just the technical, but business and political decisions around API driven resources.
Flipping from providing APIs to consuming APIs, I envision a world where I can take actions around my API designs, that focus on the availability, and integration of valuable API driven resources. As an API provider, I need as much as assistance as I can, to look at my APIs from an external perspective, and being able to take action in this area will grow increasingly important.
- Testing - Using my machine readable API definitions, I should be able to publish testing definitions, that allow the execution of common API testing patterns. I’d love to see providers like SmartBear, Runscope, APITools, and API Metrics offer services around the import of API design generated definitions.
- Monitoring - Just like API testing, I want to be able to generate definition that allow for the monitoring of API endpoints. My API monitoring tooling should allow for me to generate standard monitoring definitions, and import and run them in my API monitoring solution.
I’d say that API integration is the fastest growing area of the AP space, second only to API design itself. Understanding how an API operates, from an integrators perspective is valuable, not just to the integrator, but also the provider. I need to be thinking about integration issues early on in the API design lifecyle to minimize costly changes downstream.
I’ve laid out some of the essential actions I’d like to be able to take around my API definitions, throughout the API lifecycle. I expect the most amount of extensibility from my API design editor, in the future, and should be able to extend in any way that I need.
- Links - I need a dead simple way to take an API design, and publish to a single URL, from within my editor. This approach provides the minimum amount of extensibility I will need in the API design lifecycle.
- Marketplace - There should be a marketplace to find other custom actions I can take against my API designs. I want a way to publish my API actions to the marketplace, as well as browse other API actions, and add them to my own library.
We’ve reached a point where using API definitions like API Blueprint, RAML, and Swagger are common place, and being able to innovate around what actions we take throughout the API design lifecycle will be critical to the space moving forward, and how companies take action around their own APIs.
API Design Gallery
In my editor, I need a central location to store and manage all of my API designs. I’m calling this a gallery, because I do not want it only to be a closed off repository of designs, I want to encourage collaboration, and even public sharing of common API design patterns. I see several key API editor features I will need in my API design gallery.
- Search - I need to be able to search for API designs, based upon their content, as well as other meta data I assign to my designs. I should be able to easily expose my search criteria, and assist potential API consumers in finding my API designs as well.
- Import - I should be able to import any API design from a local file, or provide a public URL and generate local copy of any API design. Many of my Api designs will be generated from an import of existing definition.
- Versioning - I want the API editor of the future to track all versioning of my API designs. Much like managing the code around my API, I need the interface definitions to be versioned, and the standard feature set for managing this process.
- Groups - I will be working on many API designs, will various stakeholders in the success of any API design. I need a set of features in my API design editor to help me manage multiple groups, and their access to my API designs.
- Domains - Much like the Internet itself, I need to organize my APIs by domain. I have numerous domains which I manage different groups of API resources. Generally I publish all of my API portals to Github under a specific domain, or sub-domain—I would like this level of control in my API design editor.
- Github - Github plays a central role in my API design lifecycle. I need my API design editor to help me manage everything, via public and private Github repository. Using the Github API, my API design editor should be able to store all relevant data on Github—seamlessly.
- Diff - What are the differences between my API designs? I would like to understand the difference between each of my API resource types, and versions of each API designs. It might be nice if I could see the difference between my API designs, and other public APIs I might consider as competitors.
- Public - The majority of my API designs will be public, but this won’t be the case with every designer. API designers should have the control over whether or not their API designs are public or private.
My API design gallery will be the central place i work from. Once I reach a critical mass of designs, I will have many of the patterns I need to design, deploy and manage my APIs. It will be important for me to have access to import the best patterns from public repositories like API Commons. To evolve as an API designer, I need to easily create, store, and evolve my own API designs, while also being influenced by the best patterns available in the public domain.
Simple visualization can be an effective tool in helping demonstrate the value an API delivers. I want to be able to manage open, API driven visualizations, using platforms like D3.js. I need an arsenal of embeddable, API driven visualizations to help tell the store of the API resources I provide, give me a gallery to manage them.
- Browse - Give me a way to group, and organize my embeddable tools. I want to be able to organize, group and share my embeddable tools, not just for my needs, but potentially to the public as well.
A picture is worth a thousand words, and being able to easily generate interactive visualizations, driven by API resources, that can be embedded anywhere is critical to my storytelling process. I will use embeddable tools to tell the story of my API, but my API consumers will also use these visualizations as part of their efforts, and hopefully develop their own as well.
I need a common dictionary to work from when designing my APIs. I need to use consistent interface names, field names, parameters, headers, media types, and other definitions that will assist me in providing the best API experience possible.
- Search - My dictionary should be available to me in any area of my API design editor, and in true IDE style, while I’m designing. Search of my dictionary, will be essential to my API design work, but also to the groups that I work with.
- Schema.org - There are plenty of existing patterns to follow when defining my APIs, and my editor should always assist me in adopting, and reusing any existing pattern I determine as relevant to my API design lifecycle, like Schema.org.
- Dublin Core - How do I define the metadata surrounding my API designs? My editor should assist me to use common metadata patterns available like Dublin Core.
- Media Types - The results of my API should conform to existing document representations, when possible. Being able to explore the existing media types available while designing my API would help me emulate existing patterns, rather than reinventing the wheel each time I design an API.
- Custom - My dictionary should be able to be driven by existing definitions, or allow me to import and and define my own vocabulary based upon my operations. I want to extend my dictionary to meet the unique demands of my API design lifecycle.
I want my API design process to be driven by a common dictionary that fits my unique needs, but borrows from the best patterns already available in the public space. We already emulate many of the common patterns we come across, we just don’t have any common dictionary to work from, enforcing healthy design via my editor.
An Editor For Just My Own API Design Process
This story has evolved over the last two weeks, as I spent time in San Francisco, discussing API design, then spending a great deal of time driving, and thinking about the API design lifecycle. This is all part of my research into the expanding world of API design, which will result in a white paper soon, and my intent is to just shed some light on what might be some of the future building blocks of the API design space. My thoughts are very much based in my own selfish API design needs, but based upon what i’m seeing in the growing API design space.
An Editor For A Collective API Design Process
With this story, I intend to help keep the API design process a collaborative, and when relevant a public affair. I want to ensure we work from existing patterns that are defined in the space, and as we iterative and evolve APIs, we collectively share our best patterns. You should not just be proud of your API designs, and willing to share publicly, you should demonstrate the due diligence that went into your design, attribute the patterns you used to contribute to your designs, and share back your own interpretation—encouraging re-use and sharing further downstream.
What Features Would Be Part of Your Perfect API Design Editor
This is my vision around the future of API design, and what I’d like to have in my editor—what is yours? What do you need as part of your API design process? Are API definitions part of the “truth” in your API lifecycle? I’d love to hear what tools and services you think should be made available, to assist us in designing our APIs.
Disclosure: I'm still editing and linking up this post. Stay tuned for updates.
After #Gluecon in Colorado the other week, I have API design on the brain. A portion of the #APIStrat un-workshops were dedicated to API design related discussion, and API Design is also the most trafficked portion of API Evangelist this year, according to my Google Analytics.
At #Gluecon, 3Scale and API Evangelist announced our new API discovery project APIs.json, and associated tooling, API search engine APIs.io. For APIs.json, APIs.io, and API Commons to work, we are counting API providers, and API consumers creating machine readable API definitions.
With this in mind, I wanted to do some exploration--what would be possible incentives for creating machine readable API definitions?
The importance of having an API definition of available resources, is increasing. It was hard to realize the value of defining APIs with the heavy, top down defined WSDL, and even its web counterpart WADL, but with these new approaches, other incentives are emerging—incentives that live throughout the API lifecycle.
The first tangible shift in this area was when Swagger released the Swagger UI, providing interactive documentation that was generated from a Swagger API definition. Apiary quickly moved the incentives to an earlier stage in the API design lifecycle with design, mocking and collaboration opportunities.
As the API design world continues to explode, I’m seeing a number of other incentives emerge for API providers to generate machine readable API definitions, and looking to find any incentives that I’m missing, as well as identify any opportunities in how I can encourage API designers to generate machine readable API definitions in whatever format they desire.
All new links will get a URL shortener applied, as well as a screenshot taken of the page. Every night a script will run to check the HTTP status of each link used in my site—verifying the page exists, and is a valid link.
Every time link rot.js loads, it will spider the links available in the page, sync with linkrot.js API, and the API returns the corresponding shortened URL, or if a link shows a 404 status, the link will no longer link to page, it will popup the last screenshot of the page, identifying the page no longer exists.
Eventually I will be developing a dashboard, allowing me to manage the link rot across my websites, make suggestions on links I can fix, provides a visual screen capture of those I cannot, while also adding a new analytics layer by implementing shortened URLs.
Linkrot.js is just an internal tool I’m developing in private beta. Once I get up and running, Audrey will beta test, and we’ll see where it goes from there. Who knows!
I am getting psyched going through the schedule lineup of 15 sessions at API Strategy & Practice in Amsterdam. In planning the session outline, Steve, Vanessa and I listened to what the #APIStrat audience asked for after New York and San Francisco, which was more of the deep technical, as well as a balance of the business and politics of APIs.
I think our lineup delivers on this, which we've broken up into three tracks:
- Design and Development
- Service Descriptions
- Hypermedia APIs
- API Marketing & Developer Communities
- Hardware and Internet of Things (IOT)
API By Industry
- Media, Music and Audio APIs
- Civic APIs
- Enterprise APis
- APIs in Financial Services
- Community APIs
- Discovery and Trust
- Security and Testing
- High Scalability
- API Based App Development
- Business Models
This lineup of sessions represent what we are seeing across the API space, with API design coming front and center, to hypermedia moving beyond an academic discussion and actually getting traction. That is what API Strategy & Practice is about, providing a venue to have discussions about the areas that are impacting the industry.
The best thing is, this is just the session lineup, we still have workshops, keynotes, fireside chats and panels.
Over the last couple months I’ve been taking a deeper look at the API design space, trying to understand more about the tools and services that are emerging, and the different approaches being employed throughout the API design lifecycle.
I started first with trying to understand the evolving motivations behind why people are using API definitions, then I spoke with API with the creators of API Blueprint, RAML and Swagger, the three leading API design providers out there, to understand more about the vision behind their various approaches to API design.
After talking to each of the providers, I wanted to understand more about the tooling that was emerging from each of the providers:
While each of these providers have their own approach to defining APIs, and the API design lifecycle, after looking through what they offer, you start seeing patterns emerge. After reviewing what API Blueprint, RAML and Swagger bring to the table, I squinted my eyes and try to understand what some of the common building blocks are for the API design space—resulting in what I consider 22 separate building blocks:
Definition - A central, machine readable definition of an API interface, authentication and potentially data model, in XML, JSON or Markdown. (Examples: API Blueprint, RAML, Swagger)
Parser - An API definition parser, available potentially in multiple languages and open up the programmatic generation of other API building blocks.
Design Tools - User interface tools, allowing for the building of central API definitions, either in a code view or GUI view.
Versioning - Systems allowing for the versioning of API definition, keeping track of all changes, allowing for rolling back of changes to previous versions.
Forkable - The ability to fork an existing API definition, and create a new branch, that can live separately from the API definition it originates from.
Sharing - Allowing for the sharing of API definitions and other API design building blocks with other users, employing common social sharing features of preferred networks.
Collaboration - Features that allow for collaboration between users, with discussion around all API design building blocks.
Mock Interfaces - Ability to deploy mock API interfaces generated from API definitions, allowing developers to play with API versions as they are designed.
Interactive Documentation / Console - Automatically generated API documentation which allows developers to make calls against APIs as they are learning about the interface, turning API education into a hands on experience.
Notebook / Directory - A local, or cloud based storage repository, providing a single place to create and manage API definitions, and execute other API design building blocks.
Testing - Manual, automated and scheduled testing of API interfaces using their API definition as a blueprint.
Debugging - Manual, automated and scheduled debugging of API interfaces, providing detailed look inside of API calls, allowing developers to understand problems with API integrations.
Traffic Inspection - Logging and analysis of API traffic from testing, debugging and all other API usage during the API design process.
Validator - Tools for validating API calls, enabling developers to determine which types of calls will be valid, using the central API definition as guide.
Server Code Generators - Tooling that generates server side implementations using API definitions in a variety of languages.
Client Side Code Generator - Tooling that generates client side API code libraries in a variety of languages.
Github Sync - The ability to store and sync API definitions with Github, providing a central public or private repository for the definition of an API resource.
Command Line - Command line tooling for programmatic execution of all API design building blocks.
Websockets - Providing tools for API communication via websockets using the central API definition as a guide.
Translator - Tools for translating between various API definitions, allowing the transformation from RAML to Swagger, and between each of the available API definitions.
Annotation - Tools and interfaces for allowing the annotation of API definitions, providing a communication platform centered around the API design process.
Syntax Highlight - Tools and interfaces for the highlighting of API definitions, providing IDE-like functionally for API designers.
As I try to do with API management and integration, I’m just trying understand what these providers offer, and how it is helping API developers be more successful in designing quality APIs. This isn’t meant to be a perfect list, and if there are any building blocks you feel should be present, let me know.
You can follow my research in API design over at the Github repository I’m publishing everything to when it is ready. Like other areas of my research my goal is to produce a final white paper, while keeping the Github research repository a living store of API design information for the community.
As part of my research in the world of API design, I’m looking into the different approaches by API Blueprint, RAML and Swagger, to provide API definitions, services and tools that assist developers in better designing APIs. I have already look at the evolving motivations behind API definitions, and some insight into the vision behind Swagger, API Blueprint and RAML, next up is taking a look at the tooling that is emerged around each approach.
- API Blueprint - Apiary.io’s API definition language designed to allow anyone, not just developers to design APIs
To put API Blueprint to use, Apiary provides a parser:
- Snowcrash - The API Blueprint parser built on top of the Sundown Markdown parser
When it comes to tooling around API Blueprint, it is all about the Apiary.io platform:
- Apiary.io - Collaborative design, instant API mock, generated documentation, integrated code samples, debugging and automated testing
Apiary.io delivers the features we are seeing emerge around Swagger and RAML, and more:
- Server Mock - Providing a mock API interface allowing you to experiment with an API interface before you write any code
- Interactive Documentation - Auto generated API documentation that allows developers to authenticate and make live calls to an API while learning the documentation
- GitHub Sync - Apiary uses Github to store each API Blueprint, allowing it to be stored publicly or privately on Github, with automatic updating of API docs with each Github commit
- Command Line Tools - A separate command-line interface available as ruby gem, allowing for the automation and integration of API Blueprints it your regular workflow
- Traffic Inspector - Providing a proxy to run API calls through allowing the breakdown of each call to APIs, helping developers understand and debug APIs much easier
- Discussion - Communication tools within API blueprint documentation allowing team and public developer conversations
I did find two other open tools for API Blueprint:
- HTTP Call Validator - Gavel is a tool for deciding which HTTP API call is valid and which is not
- API Blueprint Testing Tool - Dredd is a command-line tool for testing API documentation written in API Blueprint format against its backend implementation.
I’d say that Apiary with API Blueprint was the first company dedicated specifically to API design. Swagger was born as a set of tools out of Wordnik, and not designed to be a product, with RAML coming later. While Swagger was pushing API design into new areas beyond just interactive docs, Apiary and API Blueprint was the first API design only startup to emerge.
During 2006-2012, API management was being standardized by pioneers like Mashery, 3Scale and Apigee--now API design is now being defined by providers like Swagger, API Blueprint, and RAML. It shows that the API space is continueing to expand and mature, increasing the need to refine not just API design, but the overall API lifecycle.
I started API Evangelist in 2010 to help business leaders better understand not just the technical, but specifically the business of APIs, helping them be successful in their own API efforts. As part of these efforts I track on what I consider the building blocks of API management. In 2014 I'm also researching what the building blocks are in other areas of the API world, including API design, deployment, discovery and integration.
After taking a quick glance at the fast growing world of API integration tools and services, I've found the following building blocks emerging:
|Pain Point Monitoring|
|Integration Touch Points|
|API Request Actions|
What else are you seeing? Which tools and services do you depend on when you are integrating one or many APIs into your applications? What tools and services would you like to see?
I'm looking at the world of API design right now, but once I'm done with that research, I will be diving into API integration again, trying to better understand the key players, tools, services and the building blocks they use to get things done.
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.