API Management News

These are the news items I've curated in my monitoring of the API space that are related to managing APIs and thought worth enough to include in my research. I'm using all of these links to better understand how APIs are being managed across a diverse range of implementations.

Learning More About Amazon Alexas Approach To Apis And Skills Development

404: Not Found

Making An Account Activity API The Default

I was reading an informative post about the Twitter Account Activity API, which seems like something that should be the default for ALL platforms. In today’s cyber insecure environment, we should have the option to subscribe to a handful of events regarding our account or be able to sign up for a service that can subscribe and help us make sense of our account activity.

An account activity API should be the default for ALL the platforms we depend on. There should be a wealth of certified aggregate activity services that can help us audit and understand what is going on with our platform account activity. We should be able to look at, understand, and react to the good and bad activity via our accounts. If there are applications doing things that don’t make sense, we should be able to suspend access, until more is understood.

The Twitter Account Activity API Callback request contains three level of details:

  • direct_message_events: An array of Direct Message Event objects.
  • users: An object containing hydrated user objects keyed by user ID.
  • apps: An object containing hydrated application objects keyed by app ID.

The Twitter Account Activity API provides a nice blueprint other API providers can follow when thinking about their own solution. While the schema returned will vary between providers, it seems like the API definition, and the webhook driven process can be standardized and shared across providers.

The Twitter Account Activity API is in beta, but I will keep an eye on it. Now that I have the concept in my head, I’ll also look for this type of API available on other platforms. It is one of those ideas I think will be sticky, and if I can kick up enough dust, maybe other API providers will consider. I would love to have this level of control over my accounts, and it is also good to see Twitter still rolling out new APIs like this.

Making An Account Activity API The Default

I was reading an informative post about the Twitter Account Activity API, which seems like something that should be the default for ALL platforms. In today’s cyber insecure environment, we should have the option to subscribe to a handful of events regarding our account or be able to sign up for a service that can subscribe and help us make sense of our account activity.

An account activity API should be the default for ALL the platforms we depend on. There should be a wealth of certified aggregate activity services that can help us audit and understand what is going on with our platform account activity. We should be able to look at, understand, and react to the good and bad activity via our accounts. If there are applications doing things that don’t make sense, we should be able to suspend access, until more is understood.

The Twitter Account Activity API Callback request contains three level of details:

  • direct_message_events: An array of Direct Message Event objects.
  • users: An object containing hydrated user objects keyed by user ID.
  • apps: An object containing hydrated application objects keyed by app ID.

The Twitter Account Activity API provides a nice blueprint other API providers can follow when thinking about their own solution. While the schema returned will vary between providers, it seems like the API definition, and the webhook driven process can be standardized and shared across providers.

The Twitter Account Activity API is in beta, but I will keep an eye on it. Now that I have the concept in my head, I’ll also look for this type of API available on other platforms. It is one of those ideas I think will be sticky, and if I can kick up enough dust, maybe other API providers will consider. I would love to have this level of control over my accounts, and it is also good to see Twitter still rolling out new APIs like this.

I Would Like To See More API Test Drives

The Azure Marketplace has the ability to test drive anything that is deployed in the Azure Marketplace. As someone who has to sign up for an endless number of new accounts to be able to play with APIs and API services, I’m a big fan of the concept of a test drive–not just for web applications, or backend infrastructure, but specifically for individual APIs and microservices.

From the Azure site: Test Drives are ready to go environments that allow you to experience a product for free without needing an Azure subscription. An additional benefit with a Test Drive is that it is pre-provisioned - you don’t have to download, set up or configure the product and can instead spend your time on evaluating the user experience, key features, and benefits of the product.

I like it. I want more of these. I want to be able to test drive, then deploy any API I want. I don’t want to sign up for an account, enter my credit card details, talk to sales, or signup for 30 day trial–I want to test drive. I want it to have data in it, and be pre-configured for a variety of use cases. Helping me understand what is possible.

I want all the friction between me finding an API (discovery via marketplace) understanding what an API does, test driving, then deployment of the API in any cloud I want. I think we are still a little bit off from this being as frictionless as I envision in my head, but I hope with enough nudging we will get there very soon.

Temporary Interaction Limits

I spend a lot of time thinking about API rate limits. How they can hurt API providers, or as my friend Tyler Singletary (@harmophone) says incentivize creativity. I think your view on rate limits will vary depending on which side of the limit you stand, as well as your own creative potential and limitations. I agree with Tyler that they can incentivize creativity, but it doesn’t mean that all limitations imposed will ultimately be good, or all creativity will be good.

I found myself contemplating Github’s recent introduction of temporary interaction limits which means “maintainers can temporarily limit who can comment, create pull requests, and open issues among existing users, collaborators, and prior contributors.” While this isn’t directly about API rate limiting, it does overlap, and provide us with some thoughts we can apply to our world of API consumption, and how we sensibly moderate the access to the digital resources we are making available online.

When it comes to real-time fetishism around the digital world those with the loudest bullhorn often get heard and think real-time is good, while I am becoming less convinced that anything gets done in a 24-hour time frame. Despite what many want you to believe, real-time does not always mean good. Sometimes it might do you some good to chill out for 24 hours before you continue commenting, posting, or increase your consumption of a digital resource, whether you want to admit it or not.

Our digital overlords have convinced us that more is better and real time is always ideal. Temporary interaction limits may not be the right answer in all situations, but it does give us another example of rate limiting by a major provider that we can consider and follow when it comes to crafting limitations around our digital resources. This is what rate limitations are all about for me, thoughtful consideration about how much of a good thing you will need each second, minute, day, week, or month. It is a great way to turn a quality digital resource into something better or possibly maintain the quality and value of a seemingly infinite resource by imposing just a handful of limitations.

Craft Your API Design Guide So You Can Move To Other Areas of The Lifecycle

I am working on an API definition and design guide for my human services API work, helping establish a framework for approaching API design as part of the human services data and API specification, but also for implementers to follow in their own individual deployments. Every time I work on the subject of API design, I’m reminded of how far behind the API sector is when it comes to standardizing what it is we do.

Every month or so I see a new company publicly share their API design guide. When they do my friend Arnaud always adds to his API Stylebook, adding it to the wealth of information available in his work. I’m happy to see each API design guide release, but in reality, ALL API providers should have an API design guide, and they should also be open to publishing it publicly, showing their consumers they have their act together, and sharing with the wider API community the best practices in play.

The lack of companies sharing their API design practices and their API definitions is why we have such a deficiency when it comes to common API patterns in use. It is why we have so many variations of web APIs, as well as the underlying schema. We have an API industry because early practitioners like SalesForce, Amazon, eBay, Flickr, Delicious, Twitter, Youtube, and others were open with their API operations. People emulate what they see and know. Each wave of the API sector depends on the previous wave sharing what they do publicly–it is how this all works.

To demonstrate even further about how deficient we are, I do not find companies sharing their guides for API deployment, management, testing, monitoring, clients, and other stops along the API lifecycle. I’m glad we are seeing an uptick in the number of API design guides, but we need this practice to spread to every other stop. We need successful providers to share how they deploy their APIs, and when any company hires a new developer, you should ALWAYS be given a standard guide for deploying, managing, testing, as well as designing APIs.

It’s not rocket science, and honestly, it’s not even technical. It just means pausing for a moment, thinking about how we approach each stop in the API lifecycle, writing up an overview, publishing, and sharing it with API stakeholders, and even the wider API community. Every company doing APIs in 2017 should be crafting an API design guide so you can get to work on guides for the other areas of your lifecycle, thinking through and standardizing your approach, and making it known to every person involved–ideally, you are also being very public about all of this, and sharing your work with me and Arnaud, so we can get the word out about the good stuff you are up to! ;-)

Taxation On Public Data Via The API Management Layer

I'm involved in some very interesting conversations with public data folks who are trying to push forward the conversation around sensible revenue generation by cities, counties, state, and the federal government using public data. I'm learning a lot from these conversations, resulting in the expansion and evolution my perceptions of how the API layer can help the government develop new revenue streams through making public data more accessible. 

I have long been a proponent of using modern API management infrastructure to help government agencies generate revenue using public data. I would also add that I'm supportive of the crafting of sensible approaches to developing applications on top of public data and API in ways that generate a fair profit for private sector actors. I am also in favor of free and unfettered access to data, and observability into the platform operations, as well as ALL commercial interests developing applications on top of public data and APIs. I'm only in favor of this, when the right amount of observability is present--otherwise digital good ol boy networks form, and the public will lose.

API management is the oldest area of my API research, expanding into my other work to eventually define documentation, SDKs, communication, support, monetization, and API plans. This is where you define the business of API operations, organizing APIs into coherent catalogs, where you can then work to begin establishing a wider monetization strategy, as well as tiers and plans that govern access to data, content, and algorithms being made available via APIs. This is the layer of API operations I'm focusing on when helping government agencies better understand how they can get more in tune with their data resources, and identify potential partnerships and other applications that might establish new revenue streams.

A portion of this conversation that I am having was involved in the story from Anthony Williams about maybe government data shouldn't always be free, where the topic of taxation came up. One possible analogy for public data access and monetization was brought up as a reference to the Vehicle-miles Traveled (VMT) tax, injecting the concept of taxation to my existing thoughts on revenue generation using API management. I've considered affiliate and reseller aspects to the API management layer before, applying percentage based revenue and payments on top of API access, but never thought about a government taxation layer existing here.

I thought my stance on revenue generation on public data using API management was controversial before, adding in concepts of taxation to the discussion is really going to invigorate folks who are in opposition to my argument. I'm sure there is a libertarian free web, open data advocate, smaller government Venn diagram in there somewhere. I'm not too concerned, as the monetization is already going on, I'm simply talking about making it more observable, and in favor of revenue generation for data stewards and government agencies. I'm confident that most won't folks in opposition won't even read this paragraph, as it's buried in the middle of this post. ;-)

I take no stance on which data, content, or algorithms should be taxed, or what that tax rate should be. I leave this to data stewards and policy makers. My objective is to just introduce folks to the concept, and marry with the existing approaches to using APIs to develop digital products and services in the private sector. However, if I was wearing my policy maker hat I would suggest thinking about this as a digital VAT tax, "that is collected incrementally, based on the surplus value, added to the price on the work at each stage of production, which is usually implemented as a destination-based tax, where the tax rate is based on the location of the customer."

My thoughts on a government tax at the API management layer are at an early stage. I am just exploring the concept on my blog--this is what I do as the API Evangelist. I'd love to hear your thoughts, on your blog. I am merely suggesting a digital VAT tax at the API contract layer around public data and APIs when commercial activities are involved. Eventually, I could see the concept spread to other sectors as the API economy becomes a reality, but I feel that public data provides us with a rich test bed for a concept like this. I'm considering reframing my argument about charging for commercial access to public data using APIs as taxing commercial usage of public data using APIs, allowing for tax revenue to fund future investment in public data and API efforts.

As I remove my API Evangelist hat and think about this concept, I'm not 100% sure if I'm in agreement with my argument. It will take a lot more polishing before I'm convinced that taxation should be included in the API management layer. I'll keep exploring, and play with a variety of potential use cases, and see if I can build a case for API taxation when public data is involved, and applications are generating surplus value in the API economy. 

API Rate Limiting At The DNS Layer

I just got an email from my DNS provider CloudFlare about rate limiting and protecting my APIs. I am a big fan of CloudFlare, partly because I am a customer, and I use to manage my own infrastructure, but also partly due to the way they understand APIs, and actively use them as part of their business, products, and services.

Their email spans a couple areas of my research that I find interesting, and extremely relevant: 1) DNS, 2) Security, 3) Management. They are offering me something that is traditionally done at the API management layer (rate limiting), but now offering to do it for me at the DNS layer, expanding the value of API rate limiting into the realm of security, and specifically in defense against DDoS attacks--a serious concern.

Talk about an easy way to add value to my world as an API provider. One that is frictionless, because I'm already depending on them for the DNS layer of my web, and API layers of operations. All I have to do is signup for the new service, and begin dialing it in for my all of my APIs, which span multiple domains--all conveniently managed using CloudFlare.

Another valuable thing CloudFlare's approach does, in my opinion, is to reintroduce the concept of rate limiting to the world of websites. This helps me in my argument that companies, organizations, institutions and government agencies should be considering having APIs to alleviate website scraping. Using CloudFlare they can now rate limit the website while pointing legitimate use cases to the API where their access can be measured, metered, and even monetized when it makes sense.

I'm hoping that CloudFlare will be exposing all of these services via their API, so that I can automate the configuration of rate limiting for my APIs at the DNS level using APIs. As I design and deploy new API endpoints I want them automatically protected at the DNS layer using CloudFlare. I don't want to have to do extra work when it comes to securing and managing web or API access. I just want a baseline for all of my operations, and when I need I can customize per specific domains, or down to the individual API path level--the rest is automated as part of my continuous integration workflows.

How I Can Help Make Sure Your API Is Ready For Use

As one of my clients is preparing to move their API from deployment to management, I'm helping them think through what is necessary to make sure their API is ready for use by a wider, more public group of developers. Ideally, I am brought into the discussion earlier on in the lifecycle, to influence design and deployment decisions, but I'm happy to be included at any time during the process. This is a generalized, and anonymized version of what I'm proposing to my client, to help make sure their API is ready for prime time--I just wanted to share with you a little of what goes on behind the scenes at API Evangelist, even when my clients aren't quite ready to talk publicly.

External Developer Number One
The first place I can help with the release of your API is when it comes to being the first external developer and fresh pair of eyes on your API. I can help with signing up, and actually making calls against every API, to make sure things are coherent and stable before putting in the hands of 3rd party developers at a hackathon, amongst partners, or the general public. This is a pre-requisite for me when it comes to writing a story on any API or doing additional consulting work, as it puts me in tune with what an API actual does, or doesn't do. The process will help provide you with a new perspective on the project after you have put so much work into the platform--in my case, it is a fresh pair of eyes that have on-boarded with 1000s of APIs.

Crafting Your API Developer Portal
Your operations will need a single place to go to engage with everything API. I always recommend deploying API portals using Github Pages, because it becomes the first are to engage with developers on Github, as part of your overall API efforts. Github is the easiest way to design, develop, deploy, and manage the API portal for your API efforts. I suggest focusing on all of the essential building blocks that any API operations should possess:

  • Landing Page
    • Tag Line - A short tagline describing what is possible using your API.
    • Description - A quick description (single paragraph) about what is available.
  • On-boarding
    • Signup Process - A link to the sign-up process for getting involved (OpenID).
    • Getting Started - A simple description, and numbered list of what it takes to get started.
    • Authentication Overview - A page dedicated to how authentication works.
    • FAQ - A listing of frequently asked questions broken down into categories, for easy browsing.
  • Integration
    • Documentation - Interactive documentation generated by the swagger / OpenAPI definition.
    • Code - Conde sample, or software development kits for developers to put to work.
    • Postman Collection - A Postman Collection + Button for loading up APIs into Postman client.
  • Support
    • Github - Set up Github account, establish profile, and setup portal as the first point of support.
    • Twitter - Set up a Twitter account, establish a presence, and make know open for business.
    • Email - Establish a single, shared email account that ca provide support for all developers.
  • Communications
    • Blog - Establish a blog using Jekyll (easy with Github Pages), and begin telling stories of the platform.
    • Twitter - Get the Twitter account in sync with communication, as well as support efforts.
  • Updates
    • Roadmap - Using Github issues, establish a label, and rhythm for sharing out the platform roadmap.
    • Issues - Using Github issues, establish a label, and rhythm for sharing out current issues with the platform.
    • Change Log - Using Github issues, establish a label and rhythm for sharing out changes made to the platform.
    • Status - Publish a monitoring and status page keeping users in tune with the platform stability and availability.
  • Legal
    • Terms of Service - Establish the terms of service for your platform.
    • Privacy Policy - Establish the privacy policy for your platform.

All of these building blocks have been aggregated from across thousands of APIs, and are something ALL successful API providers possess. I recommend starting here. You will need this as a baseline to get up and running with developers, whether generally on the web or through specific hackathons and your private engagements. Being developer number one, and helping craft, deploy, and polish the resources available via a coherent developer portal are what I bring to the table, and willing to set aside time to help you make happen.

Additionally, I'm happy to set into motion some other discussions regarding pushing forward your API operations:

  • Discovery - Establish a base discovery plan for the portal, including SEO, APIs.json development
  • Validation - Validate each API endpoint, and establish JSON assertions as part of the OpenAPI & testing.
  • Testing - Establish a testing strategy for not just monitoring all API endpoints, but make sure they return valid data.
  • Security - Think about security beyond just identity and API keys, and begin scanning API endpoints, and looking for vulnerabilities.
  • Embeddable - Pull together a strategy for embeddable tooling including buttons, badges, and widgets.
  • Webhooks - Consider how to develop a webhook strategy allowing information to be pushed out to developers, reducing calls to APIs.
  • iPaaS - Think through how to develop an iPaaS strategy to allow for integration with platforms like Zapier, empowering developers and non-developers alike.

This is how I am helping companies make sure their APIs are ready for prime time. I regularly encounter many teams who have great APIs but have been too close to the ovens baking the bread, and find it difficult to go from development to management in a coherent way. I have on-boarded and hacked on thousands of APIs. I have been doing this for over a decade, and exclusively as a full-time job for the last seven years. I am your ideal first developer and can save you significant amounts of time when it comes to crafting and deploying your API portal.

As a one person operation, I don't have the time to do this for every company that approaches me, but I'm happy to engage with almost everyone who reaches out, to understand how I can best help. Who knows, I might help prevent you from making some pretty common mistakes, and I am happy to be a safer, early beta user of your APIs--one tha will give you the feedback you are looking for.

Open Source Drag And Drop API Lifecycle Design Tooling

I'm always on the hunt for new ways to define, design, deploy, and manage API infrastructure, and thought the AWS Cloud Formation Designer provides a nice look at where things might be headed. AWS CloudFormation Designer (Designer) is a graphic tool for creating, viewing, and modifying AWS CloudFormation templates, which translates pretty nicely to managing your API infrastructure as well.

While the AWS Cloud Formation Designer spans all AWS services, all the elements are there for managing all the core stops along the API life cycle liked definition, design, DNS, deployment, management, monitoring, and others. Each of the Amazon services is available with a listing of each element available for the service, complete with all the inputs and outputs as connectors on the icons. Since all the AWS services are APIs, it's basically a drag and drop interface for mapping out how you use these APIs to define, design, deploy and manage your API infrastructure.

Using the design tool you can create templates for governing the deployment and management of API infrastructure by your team, partners, and other customers. This approach to defining the API life cycle is the closest I've seen to what stimulated my API subway map work, which became the subject of my keynotes at APIStrat in Austin, TX. It allows API architects and providers to templatize their approaches to delivering API infrastructure, in a way that is plug and play, and evolvable using the underlying JSON or YAML templates--right alongside the OpenAPI templates, we are crafting for each individual API.

The AWS Cloud Formation Designer is a drag and drop UI for the entire AWS API stack. It is something that could easily be applied to Google's API stack, Microsoft, or any other stack you define--something that could easily be done using APIs.json, developing another layer of templating for which resource types are available in the designer, as well as the formation templates generated by the design tool itself. There should be an open source "API formation designer" available, that could span cloud providers, allowing architects to define which resources are available in their toolbox--that anyone could fork and run in their environment.

I like where AWS is headed with their Cloud Formation Designer. It's another approach to providing full lifecycle tooling for use in the API space. It almost reminds me of Yahoo Pipes for the AWS Cloud, which triggers awkward feels for me. I'm hoping it is a glimpse of what's to come, and someone steps up with an even more attractive drag and drop version, that helps folks work with API-driven infrastructure no matter where it runs--maybe Google will get to work on something. They seem to be real big on supporting infrastructure that runs in any cloud environment. *wink wink*

There Is More To This Than Just Having An API

There is a reason why I encourage API providers to look at not just the technology of APIs but also invest heavily into the business and politics of API operations. There is a reason I evangelize a more open, web-based approach to doing APIs, even if you are peddling hardware and device APIs. It is because there are a number of human-centered elements present when doing APIs, that will define your services, and ultimately contribute to whether or not they are a success or a failure.

One example of this from my API news curation archives is from the Sonos API ecosystem, and a pretty big blunder in communication the audio device platform made late last year, that is significantly impacting their partnerships in 2017.  Directly from the CEPro article:

A collective cheer roared from home-technology installers at CEDIA Expo 2016, when Sonos announced an API for home-automation integration starting with Control4 (Nasdaq: CTRL), CrestroniPortLutron and Savant.

These partners – and most other respectable smart-home systems providers – have integrated with Sonos for many years, albeit with unsanctioned drivers created through reverse-engineering of a fairly straightforward UPnP-based protocol.

But the new API kind of snuck up on dealers and vendors alike, with their customers waking up to a brand new Sonos experience in late December, courtesy of an auto-update by Sonos.

The new experience was inferior to the original, with users unable to access Spotify or Amazon Music from the home automation system, except to select favorites created through Sonos’s own app.

When you are operating an API that many different businesses depend on, communication is essential. this is why I advocate that API providers always have a clear communication and support strategy, as well as the road map, issue management, and change log processes. Every single change has to be considered for its impact on the community, and you have to have a plan for how you will be communicating and supporting your API consumers needs around a change. 

This is also why API providers should be understanding the benefits of hypermedia when it comes to change management. Hypermedia design patterns provide you with a more honest approach to dealing change, one that helps make your partner's clients more fault tolerant. It is well worth the time learning about the handful of leading hypermedia media types. Any one of them would have helped Sonos manage change.

There are multiple tools in the API toolbox to help you manage change. In the en,d the most effective tools involve human to human interaction, and actually talking to your partners early on about change, and making sure you have a robust communication strategy throughout your API lifecycle. Us engineers like to think it is the API technology making the magic happen, but in the end, there is more to this than just having application programming interfaces, it is about also having the right human interfaces.

The AWS Serverless API Portal

I was looking through the Github accounts for Amazon Web Services and came across their Serverless API Portal--a pretty functional example of a forkable developer portal for your API, running on a variety of AWS services. It's a pretty interesting implementation because in addition to the tech of your API management it also helps you with the business side of things. 

The AWS Serverless Developer Portal "is a reference implementation for a developer portal application that allows users to register, discover, and subscribe to your API Products (API Gateway Usage Plans), manage their API Keys, and view their usage metrics for your APIs..[] also supports subscription/unsubscription through a SaaS product offering through the AWS Marketplace."--providing a pretty compelling API portal solution running on AWS.

There are a couple things I think are pretty noteworthy:

  • Application Backend (/lambdas/backend) - The application backend is a Lambda function built on the aws-serverless-express library. The backend is responsible for login/registration, API subscription/unsubscription, usage metrics, and handling product subscription redirects from AWS Marketplace.
  • Marketplace SaaS Setup Instructions - You can sell your SaaS product through AWS Marketplace and have the developer portal manage the subscription/unsubscription workflows. API Gateway will automatically provide authorization and metering for your product and subscribers will be automatically billed through AWS Marketplace
  • AWS Marketplace SNS Listener Function (Optional) (/listener) - The listener Lambda function will be triggered when customers subscribe or unsubscribe to your product through the AWS Marketplace console. AWS Marketplace will generate a unique SNS Topic where events will be published for your product.

This is the required infrastructure we'll need to get to what I've been talking about for some time with my wholesale API and virtual API stack stories. Amazon is providing you with the infrastructure you need to set up the storefront for your APIs, providing the management layer you will need, including monetization via their marketplace. This is a retail layer, but because your infrastructure is setup in this way, there is no reason you can't sell all or part of your setup to other wholesale customers, using the same AWS marketplace.

I had AWS marketplace on my list of solutions to better understand for some time now, but the AWS Serverless Developer Portal really begins to connect the dots for me. If you can sell access to your API infrastructure using this model, you can also sell your API infrastructure to others using this model. I will have to set up some infrastructure using this approach to better flush out how AWS infrastructure and open templates like this serverless developer portal can help facilitate a more versatile, virtualized, and wholesale API lifecycle. 

There is a more detailed walkthrough of how to get going with the AWS Serverless Developer Portal, helping you think through the details. I am a big fan of these types of templates--forkable Github repositories, with a blueprint you can follow to achieve a specific API deployment, management, or any other lifecycle objective.

An API Discovery API For Your API With Tyk

If you are selling services to the API space you should have an API, it is just how this game works (if you are savvy). I was going through Tyk's API for their open source API management solution and came across their API definitions API, which gives you a list of APIs for each Tyk deployment--baking in API discovery into the open source API management solution by default.

The API API (I still enjoy saying that) gives you the authentication, paths, versioning, and other details about each API being managed. I'm writing about this because I think that an API API should be the default for all API service providers. If you are selling me API services you should have an API for all your services, especially one that allows me to discover and manage all the APIs I'm applying your service to. 

I am expanding my definition of a minimum viable blueprint for API service providers, and adding an API API as one of the default APIs. I'm going to be adding the account, billing, and a handful of other essential APIs to my default definition. If I'm using your service to manage any part of my API operations, I need to be automating discovery, management, and billing in our relationship.

It seems obvious to me but I'm looking to provide a simple checklist that other API service providers can consider as they craft their strategy. My goal is to help make sure each stop along the lifecycle can be orchestrated in a programmatic way like Tyk.

Disclosure: Tyk is an API Evangelist partner.

The Open Guide to Amazon Web Services

I keep an eye on things that are trending daily and weekly on Github because it is a great way to discover new companies and individuals doing interesting things with APIs. While looking at this earlier this week I came across the open guide to Amazon Web Services, a pretty robust, and well organized getting started guide to everything AWS.

Here is their description of this resource out of the leading cloud computing platform:

A lot of information on AWS is already written. Most people learn AWS by reading a blog or a “getting started guide” and referring to the standard AWS references. Nonetheless, trustworthy and practical information and recommendations aren’t easy to come by. AWS’s own documentation is a great but sprawling resource few have time to read fully, and it doesn’t include anything but official facts, so omits experiences of engineers. The information in blogs or Stack Overflow is also not consistently up to date.

This guide is by and for engineers who use AWS. It aims to be a useful, living reference that consolidates links, tips, gotchas, and best practices. It arose from discussion and editing over beers by several engineers who have used AWS extensively.

I find it interesting when API providers invest in authoritative solutions like this, acknowledging the scattered and often out of date nature of blogs, QA sites, forums, and the wealth of other self-service resources available for APIs. Amazon is getting seriously organized with their approach to provider resources for developers--they have been doing this a while, and know where the pain points are. 

Amazon's organized approach, the breaking down by service, and the usage of Github are all interesting things I think are worth noting as part of my research. AWS is a tough API pioneer to showcase because they have way more resources than the average API provider, but as one of the early leaders in the API space they possess some serious wisdom and practices that are worth emulating. I'll keep going through their open guide, and see what other patterns I can extract and showcase so that my readers can consider.

An Integrations Page For Your API Solution

A new way that I am discovering the new tech services that the cool kids are using is from the dedicated integrations pages of API service providers I track on. Showcasing the services your platform integrates with is a great way of educating consumers about what the possibilities are when it comes to your tools and services. It is also a great way for analysts like me to connect the dots around which services are most important to the average user.

API service providers like DataDog, OpsClarity, and Pingometer are providing dedicated integration pages showcasing the other 3rd party platforms they integrate with. Alpha API dogs like Runscope also have integration APIs, allowing you to get a list of integrations your team depends on (perfect for another story). I'm just getting going tracking on tracking the existence of these integration pages, but each time I have come across one lately I find myself stopping and looking through each of the services included.

Directly, API integrations provide a great way to inform customers about which of the other services they use can be integrated with this platform, potentially adding to the number of reasons why they might choose to go with a service. Indirectly, API integration pages provide a great way to inform the sector about which API driven platforms are important to service providers, and their customers. After I get a number of these integration pages bookmarked as part of my research, I will work on other stories showcasing the various approaches I find.

A Service Level Agreement API For API Service Providers

I am spending some time profiling the companies who are part of my API monitoring research, specifically learning about the APIs they offer as part of their solutions. I do this work so that I can better understand what API monitoring service providers are offering, but also for the discoveries I make along the way--this is how I keep API Evangelist populated with stories. 

An interesting API I came across during this work was from the Site24X7 monitoring service, specifically their service level agreement (SLA) API. An API for adding, managing, and reporting against SLA's that you establish as part of the monitoring of your APIs. Providing a pretty interesting API pattern that seems like it should be part of the default API management stack for all API providers.

This would allow API providers to manage SLA's for their operations, but also potentially expose this layer for each consumer of the API, letting them understand SLA"s that are in place, and whether or not they have been met--in a way that could be seamlessly integrated with existing systems. An API for SLA management for API providers seems like it could also be a standalone operation as well, helping broker this layer of the API economy, and provide a rating system for how well API providers are holding up their end of the API contract.

API Access To Your Account By Default But Requires Permission To See Others

I wrote about SoundCloud beginning to require approval before developers get access to any API resources yesterday, a concept that I want to keep exploring. I'm going to be going through the APIs track on, looking for different variations of this, but before I did this I wanted to explore a couple of approaches I already had rattling around in my head.

What if, when you first sign up for API access you only get access to your own data, and content? You couldn't get access to any other users until you were approved. It seems like something that would incentivize developers to publish data and content, build their profiles out, which is good for the platform right? It will also protect other end-users from malicious activity by random developers who are just looking to wreak havoc in support of their own objectives and do not care about the platform--like we saw with Soundcloud.

A good example of how this could be applied is evident in the post yesterday by Kris Shaffer on Medium, who was looking to get his content out of the platform. I use the Medium API to syndicate blog posts to Medium (POSSEE), but there is no read API allowing me to pull my content out--I agree with Kris, this is a problem. What if Medium opened up API access, allowing us platform users to get at our own content, but then required approval of any app before there ever is access to other users content?

Some food for thought. I hear a lot of platforms say they don't do APIs because they don't want to end up with the same problems as Twitter. I think this is the result of some legacy views about public APIs that should just go away. Not all APIs are created equal, and I feel that APIs shouldn't always be just about applications, and often times are just a lifeline for platform users, helping us end-users better manage their data and content. If my internal systems and other 3rd party systems are integrated together with APIs, the likelihood I will grow dependent on the integration only increases.

Working Tips and Tricks Into Your Regular API Evangelism Efforts

I usually don't have to look very far to find good examples of API evangelism in the field, because the best technology providers are usually pretty consistent and vocal about their practices--allowing me to just pluck from my feeds, and rework as a story for my API provider readership. One of the consistent sources for me out there is from the Docker community, and from what they like to call Docker Captains.

One of the things I see regularly from this Docker community leadership is the sharing of their platform tips and tricks and in-person and online meetups. This is definitely something I recommend other API providers do when possible, but I would also recommend working to integrate the concept into your regular evangelism activities like blogging, weekly newsletter, and Tweeting.

Maybe it is something you could also open up to the rest of the community. Allowing your trusted partners, and your favorite developers to share what their tips & tricks are around API integration and usage are. The idea of tips and tricks is a pretty basic thing, but if you are working to stay creative in producing content, while also keeping things in the realm of actually helping your API developers be successful--it is one that can go a long way each week at meetups, on your blog, newsletter, Twitter, and across all the other channels you are already using to reach developers.

Be Straight Up About Internal Challenges When Hiring Your API Talent

I see an increasing number of job postings on LinkedIn and other job websites from companies who are actively seeking an API rockstar, ninja, lead, owner, or product manager, and because of my connections in the space I know that some of the intent behind them are less than sincere. Don't get me wrong, I think ALL companies should be embarking on their API journey, and if that means bringing in outside talent--get it done!

My motivation in writing this post is to help companies be more realistic during their talent search, and hiring process, as well as internally with their teams. As an IT and lead developer veteran, I have been brought in to take the reins on a number of teams and I have seen a wide range of toxic situations. I understand the internal struggles exist in all companies, but the companies that were the worst for me, were the ones where I was blindsided by the depth of the entrenchment and struggle with leadership and internal teams, either because they were in denial or were straight up bullshitting me--in hopes I might be able to wave my magic wand and just fix everything.

I've confidentially heard many stories from API product leads, and evangelists after exiting a company, or sometimes while they are still in their positions, about how entrenched internal leadership is when it comes to "innovation" and "change"--all while putting on a good show that APIs are truly the priority. I understand that companies want to look innovative, hip, agile, flexible, and all the things often associated with APIs, but bringing in API talent, only to let them hit a brick wall because they were unprepared just isn't good business.

If you are going to say that you are doing APIs, and issuing press releases, and promising your customers, partners, and internal stakeholders that you are going to do APIs, make sure you properly prepare any talent you are looking to lead the charge. I'm not saying the API journey will be easy, and you shouldn't be embarking on this journey. I am just recommending that do not go around hiring API talent, only to blindside them upon entry with entrenched, unwilling to evolve internal actors...or if this is the case just make sure you set the stage properly during the hiring process.

The API Evangelist API Management Guide

API management is the oldest area of my research. The area has been being defined since Mashery first opened its doors in 2006 and continues to be defined with the recent IPO by Apigee, and the entry of AWS into the sector with the AWS API Gateway. API management is often defined by the services offered by these companies, but also by the strategies of leading API providers in the space.

My API management research walks through the common building blocks of the space, the open source tooling, and API service providers who are serving the space. I first started this guide in 2010 and 2011 and have worked to evolve with each release, as well as the fast pace change that seems to occur in the space.

This guide touches on, and often overlaps with my other areas of research (as everything was born out of this), but should provide you with what you need as a checklist for evolving your existing API management strategy, or help you craft a brand new one for your new API. This guide has a heavy focus on a service provider led approach to API management, but with the growth in open source solutions lately, I'm working to evolve more towards a DIY approach to making it work.

I fund my research through consulting, selling my guides, and the generous support of my sponsors. I appreciate your support in helping me continue with my work and hope you find it relevant in your API journey.

Purchase My API Management Guide

Automating API Key Management Using API Service Provider APIs, And Other Open Source Solutions

I'm working my way through some of the low hanging fruit in my API notebook, when it comes to stories, and found a story thread I was working on regarding automating API key management. I'm personally storing my keys, across the private master branch for my API reps, because I don't have any super-sensitive data, and it helps me manage across hundreds of APIs, in a central way

I've talked about the need to automate API key management in the past--with the number of APIs we are using, to reach the level of security we will need, the lower level of keys will need a global refresh and management process. This level of keys most likely won't ever result in large scale security breaches, but will cause plenty headaches for both API providers and consumers.

If you use one of the following API management solutions, they provide you with an API for managing your API keys:

This will help you manage your keys, if you are an API provider, but doesn't do a lot for you to manage your API keys across providers, as an API consumer. Amazon provides a key management solution, but at first glance it appears to be something you can use to manage keys across your AWS infrastructure (am I wrong?)--which makes sense for supporting AWS objectives. ;-)

When I wrote my last post on the growing need for API key management solutions, I received a number of email and DMs, which yielded two pretty interesting open source key management solutions, Vault and Keywhiz. I'm going to evaluate these solutions for their viability as a back-end for an API driven, API key management solution, but I have a lot more work to do. 

I'm also working with a partner of mine, SecureDB, and consider the possibility fo developing an encrypted API key management solution, which then would be accessible via their secure API. They are looking for some interesting solutions like this to be developed on their platform, so if you are a developer, and looking for a viable micro startup idea--let me know.

As with everything in my world, the concept of automating API keys using APIs, and managing of keys across API platforms, is a work in progress--stay tuned!

Adding An OAuth Scope Page As One Of My API Management Building Blocks

I've had a handful of suggested building blocks when it comes to authentication, as part of my API management research, but after taking a look at the OAuth Scopes page for the Slack API, I'm going to add another building block just for listing out OAuth scopes.

For platforms who provide OAuth, scopes are how access to users content and data is being broken down, and negotiated. When it comes to industry levels, OAuth scopes are how power and influence is being brokered, so I'm going to start tracking on how leading providers are defining their scopes--I am sure there are some healthy patterns that we all can follow here.

I have had the pleasure of sitting in on OAuth negotiations between major utility providers, as part of my work with the White House and Department of Energy in the past. This work has given me a glimpse into the future of how access and sharing of data will be negotiated in the future, with OAuth scopes and APIs playing a central role.

It will take me some time to standardize how I gather, store, and publish the OAuth scopes for each API, but I can get started by bookmarking any provider who shares their OAuth scopes, and encourage other API providers to do, by suggesting a formal OAuth scopes page as one possible building block you should consider when crafting your API strategy.

The Emerging Need For API Key Management Solutions

An API key management service targeting Drupal developers came across my radar this week. The service is very focused, in that it is a Drupal module, and is focused on helping Drupal developers manage the keys they use across a single app or installation, but I think it represents a potentially larger trend.

I think this particular solutions is just a symptom of a growing problem for developers of any type--how do you manage the number of keys you are depending on for you application(s). API consumers are in need of a plug and play way of to store, access, and manage the increasing number of API keys they put in use, otherwise we will be looking at a pretty serious security problem, adding to the existing security issues API providers and consumers face.

If you need evidence of the viability of API Key management solutions, AWS has one. Ok, why don't developer just use AWS? Well they should if it makes sense, but we also need other competing, and complimentary key management solutions, to ensure a healthy API space. Not all users are going to need full-blown IAM solutions, they just need a simple, encrypted place to put all their keys, and some utilities to help them manage them. 

Personally, I store my keys in a JSON config file stored in the private Github repo for any application I develop, and for each org, I have some crude API key management utilities to help me manage turnover. My server apps can cache the config file locally, and my client side apps run on Github Pages, using SSL, and Github OAuth to open up API key access they need.

I will be keeping an eye out for more API key management solutions, and begin the process of documenting the building blocks of these product and services, like I do with other areas. If you are looking to develop an API key management solution, feel free to reach out, as I have some feedback for your road-map along the way, and existing tools you could use to make it easier. 

Adding a Suggested API Definition for API Portals to My API Management Spec Collection

One layer I am working to add to my API research, are machine readable API definitions that I find, or generate from the APIs of the API service providers I keep an eye on. Within this new layer I'm aggregating these API the specs of the companies who are offering services within the emerging areas of the API sector.

The first area I've started aggregating is within API management. 3Scale was very forward leaning with their willingness to open up their API definitions for their own API management infrastructure APIs. These are API specs that describe all of the features of the 3Scale API management platform, and represent one possible blueprint that API management service providers could emulate.

I have four separate API definitions included from 3Scale on my new page, something that could be broken down further if it makes sense. I also just added a suggested API definition for API portals--crafted by the APIMATIC team. They thought my idea for defining a common set of definitions across the 17+ areas I monitor was an interesting cenough oncept, and was something they wanted to explore further with me.

Zeeshan Ejaz Bhatti of APIMATIC pulled together this spec:



This is just one potential starting point for providing a common interface for managing your API portal. Zeeshan feels that , if "API-Portals-as-a-Service", and other API management providers agreed on a common publish API format, it would benefit other API service providers like APIMATIC who are providing services to their customers via these API portals.

I agree with Zeeshan, and might play around adding an API facade for managing your API portal using Github + Jekyll, like I do with my standard API Portal template. This is all work in progress. Right now I am just aggregating the API definitions for API service providers that have APIs. In my opinion this layer of the API space will differentiate API service providers from each other, demonstrating which ones will actually scale in the fast growing the API economy.

Next I'm taking API monitoring services like Runscope and API Science, and aggregate their API definitions as part of my research.

Establishing A Common API Definition That API Management Providers Can Use

I mentioned the concept of what I call API building blocks coming to life by API service providers yesterday. These are the features provided from API service providers that are made accessible via APIs. Mind blowing right? API service providers having APIs? Which then allows API providers to programmatically manage the operations of their own APIs? Who would have ever thought!! Actually it is a pretty clear example of API service providers who are kind of full of it, when they do not offer their own APIs--meaning they are telling you about the importance of APIs, but not actually practicing what they preach. It is kind of like API providers who do not use their own APIs in their applications (dogfooding).

Anyhoo. I have done a lot of work to define the common building blocks across API service providers, spanning over 17 stops along the API lifecycle, and part of the next phase of my research is to connect these building blocks to actual API definitions that can help automate these vital API features. First up, I took the 3Scale API, and generated this list of common building blocks represented in the API for their API infrastructure.


  • Authorize (App Id authentication pattern)(GET) - Read-only operation to authorize an application in the App Id authentication pattern
  • Authorize (API Key authentication pattern)(GET) - Read-only operation to authorize an application in the App Key authentication pattern
  • Authorize (OAuth authentication mode pattern)(GET) - Read-only operation to authorize an application in the OAuth authentication pattern


  • Report (App Id authentication pattern)(POST) - Report the transactions
  • Report (API Key authentication pattern)(POST) - Report the transactions
  • Report (OAuth authentication pattern)(POST) - Report the transactions to

Authorization + Reporting

  • AuthRep (Authorize + Report for the App Id authentication pattern)(GET) - Authrep is a 'one-shot' operation to authorize an application and report the associated transaction at the same time
  • AuthRep (Authorize + Report for the API Key authentication pattern)(GET) - Authrep is a 'one-shot' operation to authorize an application and report the associated transaction at the same time
  • AuthRep (OAuth authentication mode pattern)(GET) - Authrep is a 'one-shot' operation to authorize an application and report the associated transaction at the same time in the OAuth authentication pattern

Account Management

  • Account Feature List(GET) - Returns the list of the features available to accounts
  • Account Feature Create(POST) - Create an account feature
  • Account Feature Read(GET) - Returns an account feature
  • Account Feature Update(PUT) - Updates an account feature
  • Account Feature Delete(DELETE) - Deletes an account feature
  • Account Plan Feature List(GET) - Returns the list of the features associated to an account plan
  • Account Plan Features Create(POST) - Associate an account feature to an account plan
  • Account Plan Features Delete(DELETE) - Deletes the association of an account feature to an account plan
  • Account Plan List(GET) - Returns the list of all available account plans
  • Account Plan Create(POST) - Creates an account plan
  • Account Plan Read(GET) - Returns the account plan by id
  • Account Plan Update(PUT) - Updates an account plan
  • Account Plan Delete(DELETE) - Deletes and account plan
  • Account Plan set to Default(PUT) - Set the account plan to be the default one
  • Account List(GET) - Returns the list of the buyer accounts (the accounts that consume your API)
  • Account Find(GET) - Find an account by the username or email of its users (username takes precendence over email)
  • Account Read(GET) - Returns a buyer account
  • Account Update(PUT) - Updates a buyer account by id
  • Account Delete (DELETE) - Deletes a buyer account
  • Account Change Plan(PUT) - Changes the account plan of the buyer account
  • Account Approve(PUT) - Approves the account (changes the state to live)
  • Account Reject(PUT) - Rejects the account (changes the state to rejected)
  • Account Reset to Pending(PUT) - Resets the state of the account to pending
  • Account Set Credit Card(PUT) - Associates credit card tokens and billing address to an account
  • Account Delete Credit Card(DELETE) - Removes all credit card info of an account
  • Account Message(POST) - Sends a message to the account
  • Account Read(GET) - Returns your account

Application Management

  • Application Plan Feature List(GET) - Returns the list of features of the application plan
  • Application Plan Feature Create(POST) - Associates a feature to an application plan
  • Application Plan Feature Delete(DELETE) - 
  • Limits List per Application Plan(GET) - Returns the list of all limits associated to an application plan
  • Limit List per Metric(GET) - Returns the list of all limits associated to a metric of an application plan
  • Limit Create(POST) - Adds a limit to a metric of an application plan
  • Limit Read(GET) - Returns a limit on a metric of an application plan
  • Limit Update(PUT) - Updates a limit on a metric of an application plan
  • Limit Delete(DELETE) - Deletes a limit on a metric of an application plan
  • Pricing Rules List per Metric(GET) - Returns the list of all pricing rules associated to a metric of an application plan
  • Pricing Rules List per Application Plan(GET) - Returns the list of all pricing rules associated to an application plan
  • Application Plan List (all services)(GET) - Returns the list of all application plans across services
  • Application Plan List(GET) - Returns the list of all application plans of a service
  • Application Plan Create(POST) - Creates an application plan
  • Application Plan Read(GET) - Returns and application plan
  • Application Plan Update(PUT) - Updates an application plan
  • Application Plan Delete(DELETE) - Deletes an application plan
  • Application Plan Set to Default(PUT) - Makes the application plan the default one
  • Application List (all services)(GET) - Returns the list of applications across all services
  • Application Find(GET) - Finds an application by keys used on the integration of your API and 3scale's Service Management API or by id (no need to know the account_id)
  • Account Fetch Account Plan(GET) - Returns the account plan associated to an account
  • Application Key List(GET) - Lists app keys of the application
  • Application key Create(POST) - Adds an key of an application (valid only on the authentication mode app_id/app_key or oauth)
  • Application key Delete(DELETE) - Deletes an key of an application (valid only on the authentication mode app_id/app_key or oauth)
  • Application Referrer Filter List(GET) - Lists referrer filters of the application
  • Application Referrer Filter Create(POST) - Adds a referrer filter to an application
  • Application Referrer Filter Delete(DELETE) - Deletes a referrer filter of an application
  • Application List(GET) - Returns the list of application of an account
  • Application Create(POST) - Create an application
  • Application Read(GET) - Returns the application by id
  • Application Update(PUT) - Updates an application
  • Application Change Plan(PUT) - Changes the application plan of an application
  • Application Create Plan Customization(PUT) - Creates a customized application plan for the application
  • Application Delete Plan Customization(PUT) - Deletes the customized application plan of the application
  • Application Accept(PUT) - Accepts an application (changes the state to live)
  • Application Suspend(PUT) - Suspends an application (changes the state to suspended)
  • Application Resume(PUT) - Resume a suspended application

User Management

  • User List(GET) - Returns the list of users of an account
  • User Create(POST) - Creates a new user of the account (account_id)
  • User Read(GET) - Returns the user of an account
  • User Update(PUT) - Updates the user of an account
  • User Delete(DELETE) - Deletes a user of an account
  • User change Role to Member(PUT) - Changes the role of the user to member
  • User change Role to Admin(PUT) - Changes the role of the user to admin
  • User Suspend(PUT) - Changes the state of the user to suspended
  • User Unsuspend(PUT) - Change the state of the user back to active
  • User Activate(PUT) - Activate the user of an account
  • Limit List for End User Plans (GET) - Returns the list of all limits associated to a metric of an end user plan
  • Limit Create for End User Plans(POST) - Adds a limit to a metric of an end user plan
  • Limit Read for End User Plans(GET) - Returns a limit on a metric of an end user plan
  • Limit Update for End User Plans(PUT) - Updates a limit on a metric of an end user plan
  • Limit Delete for End User Plans(DELETE) - Deletes a limit on a metric of an end user plan
  • End User Plan List (all services)(GET) - Returns the list of all end user plans across services
  • End User Plan List(GET) - Returns the list of all end user plans of a service
  • End User Plan Create(POST) - Creates an end user plan
  • End User Plan Read(GET) - Returns and end user plan
  • End User Plan Update(PUT) - Updates an end user plan
  • End User Plan set to Default(PUT) - Makes the end user plan the default one
  • End User Read(GET) - Returns the end user by id
  • End User Create(POST) - Create an end user
  • End User Delete(DELETE) - Deletes a end user
  • End User Change Plan(PUT) - Changes the end user plan of an end user
  • User List (provider account)(GET) - Lists the users of the provider account
  • User Create (provider account)(POST) - Creates a new user in the provider account
  • User Read (provider account)(GET) - Gets the user of the provider account by id
  • User Update (provider account)(PUT) - Modifies the user of the provider account by id
  • User Delete (provider account)(DELETE) - Deletes the user of the provider account by id
  • User change Role to Member (provider account)(PUT) - Changes the role of the user of the provider account to member
  • User change Role to Admin (provider account)(PUT) - Changes the role of the provider account to admin (full rights and privileges)
  • User Suspend (provider account)(PUT) - Changes the state of the user of the provider account to suspended, remove the user's ability to sign-in
  • User Unsuspend (of provider account)(PUT) - Revokes the suspension of a user of the provider account
  • User Activate (provider account)(PUT) - Changes the state of the user of the provider account to active, to be done after sign-up


  • Method List(GET) - List the methods of a metric
  • Method Create(POST) - Creates a method under a metric
  • Method Read(GET) - Returns the method of a metric
  • Method Update(PUT) - Updates a method of a metric
  • Method Delete(DELETE) - Deletes the method of a metric
  • Metric List(GET) - Returns the list of metrics of a service
  • Metric Create(POST) - Creates a metric on a service
  • Metric Read(GET) - Returns the metric of a service
  • Metric Update(PUT) - Updates the metric of a service
  • Metric Delete(DELETE) - Deletes the metric of a service
  • Application Usage by Metric(GET) - Returns the usage data for a given metric (or method) of an application
  • Service Usage by Metric(GET) - Returns the usage data of a given metric (or method) of a service
  • Service Top Applications(GET) - Returns usage and application data for the top 10 most active applications of a service

Service Management

  • Service Feature List(GET) - Returns the list of all features of a service
  • Service Feature Create(POST) - Creates a feature on a service
  • Service Feature Read(GET) - Returns a feature of a service
  • Service Feature Update(PUT) - Updates a feature of a service
  • Service Feature Delete(DELETE) - Deletes a feature of a service
  • Service Plan Feature List(GET) - Returns the list of features of a service plan
  • Service Plan Feature Add(POST) - Associates an existing feature to a service plan
  • Service Plan List (all services)(GET) - Returns a list of all service plans for all services
  • Service Plan List(GET) - Returns a list of service plans for a service
  • Service Plan Create(POST) - Creates a new service plan in a service
  • Service Plan Read(GET) - Returns a service plan by id
  • Service Plan Update(PUT) - Updates a service plan by id
  • Service Plan Delete(DELETE) - Deletes a service plan by id
  • Service Plan set to Default(PUT) - Sets the service plan as default
  • Service List(GET) - Returns the list of all services
  • Service Create(POST) - Creates a new service
  • Service Read(GET) - Returns the service by id
  • Service Update(PUT) - Update the service
  • Signup Express(POST) - This request allows to reproduce a sign-up from a buyer in a single API call

Billing Management

  • Invoice List by Account(GET) - Returns the list of all invoices by account
  • Invoice by Account(GET) - Returns an invoice by id
  • Invoice List(GET) - Returns the list of all invoices
  • Invoice(GET) - Returns an invoice by id
  • Invoice(PUT) - Modifies the state of the invoice
  • Invoice Line Items List(GET) - Returns the list of all line items of an invoice
  • Invoice Payment Transactions List(GET) - Returns the list of all payment transactions of an invoice


  • Webhooks List Failed Deliveries(GET) - Lists of webhooks that could not be delivered to your end-point after 5 trials
  • Webhooks Delete Failed Deliveries(DELETE) - Deletes failed deliveries records

I've been using a subset of the 3Scale API management API definition as my standard blueprint for other API providers should follow, for a while now. All API providers should have an API for base API account management--meaning your API consumers should be able to manage their accounts, services, apps, and billing via an API. This will be a differentiation between API providers in the near future, and if you aren't up to speed, developers will be looking elsewhere.

This portion of my work is in response to a group of open source API management providers looking to encourage interoperability between their platforms, and what better way to do this than a common API management definition. While not all API management solutions will have exactly the same features, if they can speak a common, API defined language, the better off the entire API space will be.

This is something I want to encourage across all 17+ of the API service areas I track on. I'm going to take a look at API monitoring, and also try to generate a common outline from definition across some of the service providers I track on. I'm using API definitions to generate these outlines, and potentially merging across multiple API service providers. If you are one of the API service providers I track on, and have an API definition, make sure I have link so I can include in thi sportion of my research.

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.