23 Oct 2015
I started playing with the possibilities when it comes to API deployment using virtual containers like Docker early this year, exploring the constraints this approach to API deployment introduced, on my own infrastructure. The process got my gears turning, when it comes to deploying very simple data, content, and algorithmic APIs into any environment that runs Docker.
As 2015 has progressed, I'm seeing containers emerge as part of more stops along the API life-cycle, specifically in deployment and virtualization. A new one that just came across my radar is API PLUG. I haven't played with the containerized API deployment solution yet, but after watching video, and looking through site it seems in line with what I'd expect to see from a next generation, containerized, API deployment solution.
Overlapping with my previous post on reconciling API orchestration, I'm seeing several stops along API lifecycle present in API PLUG, beyond just API deployment, it allows you to design, deploy, and document your API which moves well into the world of API management. As I'm seeing with other emerging solutions like API Studio from Apigee, I predict we will see testing, monitoring, and other critical layers of the API life-cycle emerge as orchestration layers of API PLUG.
I've added API PLUG to my API deployment research, and I am still considering the best way to include them in other areas of my API research. I'm increasingly finding that modern API management solutions are spanning multiple areas of the API life-cycle, which further encourages me to modularize my research, but also tells me I'm going to need to create some sort of Venn Diagram visualization to help me better understand the reach of emerging API products and services.
Anyways, more to come on API PLUG as I play with, and listen to the stories they tell via their blog, Twitter, and Github accounts (I can only find a Twitter account, but I'm sure they are working on that! ;-).
See The Full Blog Post
22 Oct 2015
Marketing your products and services in the API sector can often look very different than marketing of products and services in other sectors. Developers are a very different target audience, and to make things even more complicated, not all developers are created equal! Open developer are not like the enterprise developer, and healthcare developers won't have much in common with device-based, Internet of Things developers.
How to market your API has been a session at every APIStrat since we did the first conference in New York City back in February of 2013, and we just announced the latest edition of marketing for APIs at @APIStrat in Austin in November. Here is the lineup we have for this round:
With the session being chaired by:
The marketing session at @APIStrat is one of the tracks that is meant for API users of all types, from business to developer, and is something that should be attended whether you are at a startup, or leading things in the enterprise.
There is less than a month left before @APIStrat Austin 2015, so make sure and get registered before tickets are sold out. There are also still a couple of keynotes left to announce, so stay tuned for some last minute highlights.
We'll see you in Austin, November 18th, 19th, and 20th.
See The Full Blog Post
22 Oct 2015
It has been a year or two since I've given any deep thought to the Twitter ecosystem. There has been such little meaningful action to come out of the social platform over the last couple years, I had all but given up on it being a platform with any sort of future for developers.
When Jack Dorsey apologized and solicited feedback from the community this week, I honestly felt I didn't have much to offer when it comes to advice--I just wasn't prepared. Twitter does almost everything right when it comes to their developer ecosystem...well on the surface, where they do fail, is within the most critical areas of API operations:
- Communication - Twitter communicates about the usual mundane API platform stuff, but really lacks a tone and substance that really cuts through the BS for developers. In my opinion it will take years to recover from the tone set by Dick Costolo & Ryan Sarver--they just did not respect developers at all, and it showed. This isn't something you recover from quickly.
- Access & Rate Limits - While communications around access level and rate limits have gotten much more clearer, with a dedicated area in dev portal, and available inline within documentation, it will take going the extra mile before developers feel like there is truly a level playing field. It will require more API access to account level usage, notifications, dashboards, etc. to heal these wounds--real-time communication.
- Business Model - There is just no clear business model evident from the developer ecosystem--something that showcases how Twitter is making money, where the API fits into this, and the opportunity for developers to play in this game. I've broken down the pricing confusion involved with using the REST API, and Streaming API, and tried to understand across the different levels of access--even though my research is dated, the confusion still exists. There is no clarity when it comes to how I can grow my usage of Twitter (as a startup), therefore many resort to very bad behavior to make ends meet.
- Personality - There is no personality or face to the Twitter platform, thus it always defaults up the chain to current CEO. Maybe a new director of platform came on after Ryan Sarver left, but I couldn't tell you who it was. The platform needs a leader who will set the same tone Jack Dorsey is trying to set by returning to the CEO Position--Twitter needs a Jack who is specifically in charge of the platform vision, message, and will be the friendly face of the platform turnaround.
The lack of communication, overall tone, and lack of transparency and clarity around access, rate limits, and the business model has just left a bad taste in the mouths of Twitter developers. I use the Twitter API actively as part of my business, but I would never consider building a new product that depends on the Twitter API--never, and I know many other developers feel the same.
I've long moved on from my utopian views of what the Twitter API could have been, there are too many powerful actors who are investors, and partners now for this ever to be a reality. I do not think Twitter should entertain and do business with ALL 3rd party developers, and eliminate rate limits--I am more experienced in API operations than this. However Twitter has to provide a clear ladder that developers can climb when it comes to accessing the API, ascending all the way up to partner levels, with transparency all along the way.
Twitter has to be communicating with the community at every step, and honestly the community needs to get better at communicating with Twitter as well. I respect the challenge that Twitter has when it comes to managing a million developers, and know these things are not easy, and it makes me happy to see Jack taking a clear stance, and reach out to the community for feedback.
As Jack Dorsey said, transparency is the key. Transparency around API access, rate limits, the road-map, business model, partner and developer revenue opportunities, will be critical going forward. It makes me happy to see language like "Developer Rules of the Road" finally gone from the legal side of platform operations--it was language like this that set a really bad tone for developers. I really hope Twitter can turn this corner, and reboot its ecosystem, as the platform plays a critical role in almost every industry, and in my opinion is the most important API out there today. i would really like to be able to showcase Twitter as a platform that all API providers should emulate once again.
See The Full Blog Post
22 Oct 2015
I just had a call with one of my newer API partners, working with them on crafting version 1.0 of their API evangelism strategy, and the subject of what content to generate, and which channels to use, when building up their brand arose. In my work, about 90% of the approaches I see implemented by API providers is a traditional PR strategy, where you create content, and push to popular channels to do the work of syndicating the message. While this approach works, and is something I recommend you do, I have a different way of building up my brand, and the partner or community brands that I invest in.
All of this begins with something that truly brings value to the table for everyone involved, without this, my approach will not work. Once you have something of value, you start working directly with this value, building things, experimenting and playing, while telling the story all along the way. If it isn't something you'd use yourself, and be able to innovate with, why would you expect anyone else to. If value truly exists around products, services, and tooling associated with a brand, you will build momentum with each story you tell, eventually encouraging others to do the same.
An example of this in the wild is with the fast growing API definition Swagger. I started paying attention to Swagger closely in 2011, and by mid 2014 I had gone all in with Swagger, and integrated into my own platform, and tooling, resulting in 265 stories that reference swagger over the last four years. Let me show the value driven by this type of storytelling--here are the plotting of my stories over the last four years:
Here is a plotting of growth of the Swagger according to Google Trends:
This is how you build brand awareness organically. I'm not saying I'm solely responsible for Swagger's success--it all started with the value brought to the table by Tony Tam. Secondarily it was the community who ultimately integrated Swagger into their platforms, used Swagger UI for displaying their API documentation, and innovated in the numerous other areas of API operations where the API definition format has been applied. Most importantly, it has taken the storytelling of the community, about what they have done, that got us to where we are at in 2015 with the Swagger brand.
Along with the value brought to the table by Tony, and the community, I do feel I played a significant role in where the Swagger brand is today. I did this through building tooling with Swagger, searching out what others were doing, and telling the story all along the way. I wrote 160 stories in 2015 alone, and I did this all via my own blog. I beat this drum so loud, and so consistently, others wrote about what I was doing in top tier blogs like InfoQ and TechCrunch, as well as on other company and developer blogs.
This is the power of storytelling. This isn't marketing, and isn't about products or services--it is about generating valuable exhaust around something API related, and telling the story along the way. This is something I enjoy helping API providers, and service providers understand as they try to differentiate themselves in 2015, and for a select few partners, I will be doing this around the value they bring to the table, across the API Evangelist network.
See The Full Blog Post
22 Oct 2015
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.
See The Full Blog Post
16 Oct 2015
I have used the Federal Agency Directory API for quite some time to lookup federal government agencies. USA.gov has some highly valuable, and simple APIs including the Social Media Registry API, which I find extremely useful. They recently added a new one for searching government websites that do not end in .gov.
The Non-.gov URLs APIs allows you to search for all websites that end in .com, .org, .edu, or other top-level domains, including:
I find the APIs coming out of USA.gov to be excellent examples of what ALL government agencies should be doing. The APIs don't have to be complicated, just provide simple read, and sometimes write access to valuable government data that should be public.
I am going to prioritize the creation of an API definition for USA.gov, and wrap their APIs in an APIs.json file, and add to my federal API stack. The more of these APIs I have at my disposal, the more efficient I am at when it comes to opening up government data, and making existing API resources available across my research.
See The Full Blog Post
16 Oct 2015
I've been working on expand upon my API security research, but it can be difficult to find API focused security solutions. Exactly what is security when it comes to APIs can vary. Are you looking to secure your APIs? Are you looking to secure your data or content using an API? This is why I started a research projects so that I can turn on my keyword monitoring, and begin scouring the landscape in real-time--the more I conduct research in an area, the better I get at it.
The best part of my research is that sometimes when I write about things, companies just come to me. This happened the other week, with an encrypted database API provider called SecureDB. What this brand new API driven platform provides is default security for your accounts, data, files, and settings--exactly what we need in this cyber-insecure world we have created for ourselves.
I do not store any sensitive data, but if I did, I would not want to be in the business of storing it. Period! SecureDB gives you everything you need to manage your users account and identity, create the data stores you need, and store your appilcations files and settings in a secure environment. All identity data is encrypted by default, and you get to set the encryption levels for all your data stores, allowing you to make sure everything sensitive is not readable on the server, even if it is compromised.
SecureDB is just getting started, but they have a lot of things in the works, including on-premise, containerized implementations, version that run on Heroku, white label solutions, and much more. I will be working with them to help them craft a marketing and storyteling strategy around their encrypted database solution, and establishing a deeper partnership between them and API Evangelist.
I'm pretty stoked on my ability to attract these types of API service providers just by publishing my research regularly, and talking about the areas these companies are providing solutions in. I'm just telling the first story about SecureDB to let you know they are out there, and get them established in my monitoring system, and overall research--stay tuned for much more on SecureDB, and the security solutions they provide--I couldn't think of a better time for an API like this, we are so going to need it.
See The Full Blog Post
15 Oct 2015
It is up to API providers to establish a coherent approach regarding how they rollout and manage their APIs, something that historically has just involved deploying and managing, but in the last couple of years we have seen more formal approaches emerge, something we are all calling the API lifecycle.
In 2012, after we started standardizing our API development and management thinking using API definitions, the expansion of the API lifecycle was set into motion with the introduction of an API design-first way of thinking from the Apiary team. API definitions allowed us to get our development and management house in order, but also begin collaborating, mocking, and having a conversation around our API designs, way before we began the costly process of writing code.
In 2015, I am tracking on API definitions driving over 17 separate stops along this fast evolving API lifecycle. While some API providers who are further along in their API journey are incorporating all of these stops, many API providers who are just getting going, are still learning about all the stops along this modern API lifecycle. Part of this evolution is establishing just exactly what is your companies API lifecycle, something that can be a very personal thing, and we'll need more of our tooling to help us quantify this.
This is why I was happy to see evidence of API lifecycle management built into the tooling with the new AWS API Gateway. In my earlier post on the potentially very powerful API orchestration with the Amazon API Gateway:
Going beyond the types of integration you can employ when crafting, and deploying APIs using the Amazon API Gateway, the platform also provides a way to define stages that APIs will exist in from design, development, QA, production, or any other stage you wish. I like the concept of having a stage defined for each API, designating where it exists on the API life-cycle. I tend to just have dev and prod, but this might make me consider this a little more deeply, as it seems to be a big part of defining the API journey.
In my opinion, this is a sign of things to come. Right now it is just basically a way to tag your APIs, and define which stage of the API lifecycle they are in, but I can see see these stages being used to organize various stops along the API lifecycle, in a meaningful way for your API team. You could put testing and performance as part of your QA stage, and you can setup monitoring and security for your APIs that are in production, and much more.
While it is still coming into focus for me, I see the 17+ stops along the API lifecycle as something that could be organized into these various API lifecycle stages. I do not think there will be one API lifecycle blueprint to rule them all, but this new approach would allow API teams to craft their own vision, and allow them to share these blueprints for other teams to follow, either internally, or even publicly.
I hope we'll see more API service providers consider where they fit into the overall API lifecycle of their consumers, and provide features that helps users define what this means to their team. Maybe eventually we'll end up with a common language and tooling for helping API providers discuss and operate within a more coherent, flowing, and meaningful API lifecycle.
See The Full Blog Post
15 Oct 2015
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 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 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 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 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
- 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.
See The Full Blog Post
14 Oct 2015
Maybe I've looked at too many APIs, but I feel that APIs are very telling of the overall culture of a company. APIs that are trusting, tend to open up a full stack of APIs, including POST, PUT (or PATCH), and DELETE functionality, giving developers access to all, or nearly all functionality available via a platform.
I do not feel that platforms are required to open up everything, but the amount of what they open up, does tells a lot about how a company is thinking. While I find many companies are not fully up to speed on the benefits a modern API management strategy, and the control it gives you over resources and API consumers, I think many just do not trust anyone outside the firewall, and think they know best when it comes to everything.
APIs are not for every company, and I do not think everybody should have any API, but I do want API providers to be aware of how telling their approach will be about their motives behind having an API. You should not see this as a negative lesson, it will help you think about your company from the outside-in, this is one of the most important aspects of the API journey in my opinion.
A journey you should begin as soon as possible, if you think you can make it work in a positive way.
See The Full Blog Post
14 Oct 2015
NASA just launched two new APIs, as part of their open data efforts. I find the APIs they offer to be simple, and very inspirational examples of what an API can be. Maybe I just love space, but seeing these well designed, very fun APIs out of our countries space agency is just cool.
They added a Near Earth Asteroids API, and a Mars Rover Photos API, and they also understand the value of telling the story of the release on their blog. Remember API providers, if you launch an API in the woods and don't blog about, nobody will know about it--storytelling is one of the most important tools in your toolbox.
Also, your APIs don't have to be complicated, and overthought. Just providing GET access to interesting images and other content like NASA is doing can really go a long ways in generating attention (it got me to write a blog post). You can see this in action with both their APIs, and their approach to their API portal--I look forward to seeing what APIs they release next!
See The Full Blog Post
14 Oct 2015
I wrote about the ability to convert between multiple API definition formats using API Transformer the other day, a solution being developed by the APIMATIC team, and shortly after posting, the LucyBot team pointed out they are working on a similar tool. This is one of the reason I try to write these posts, it always brings folks out of the woodwork.
It is good to see multiple efforts out there. Converting of API definition formats is a fast growing need for both API providers and consumers, something that is only going to grow with the adoption of popular API definition formats. I feel it is a healthy sign that standard tooling for converting common API has emerged, and an even better sign that there will be a diverse selection in this tooling.
It looks like the Lucybot converter is a little behind API Transformer, but I'm sure they will get caught up soon. I'm eager to see how these API definition conversion service providers keep up with each version of API definitions as they evolve, as well as new players who enter the game. If they can do successfully they will possess some very valuable data around which API definitions are being put to use by API providers and consumers.
See The Full Blog Post
13 Oct 2015
If you have followed my work since 2010, you know I pull out what I call the common building blocks of originally just API management, but over the last five years this has grown to 17 areas of the API life-cycle. My goal is to better understand the common features offered by API service providers, but only the ones that will also matter to API consumers at the same time.
In the last couple months I started tracking on how these API building blocks match to actual APIs offered by the API service providers I monitor. What do I mean? Well, when you consider the common building blocks offered offered by API management providers, these building blocks come to life when you look at the API offered by 3Scale.
Moving down the lifecylce, you can see this in action with the Runscope API in the area of API monitoring. The RunScope API allows API providers and consumers to realize API monitoring and testing in a programmatic way, going beyond the web interface they provide to their users. While the features available via RunScope, and via the APIs are not a one to one match, they represent a very important start.
This is where API providers become API consumers, accessing common building blocks they will need to operate their platform. This is also where API providers practice what they preach, and also become API providers, in addition to just selling services to API providers--an important distinction that separate the API service providers who are further along in their journey.
If you are an API service provider, and do not offer an API to your customers, matching as many of the features available in your interface, my prediction is you won't last long in the current fast moving landscape.
See The Full Blog Post
10 Oct 2015
One of the things that really bothers me in the API space is when API service providers are too competitive, establish silos, don't use APIs themselves, and refuse to provide interoperability with other service providers. It is the API space y'all, this shit needs to work together, if we expect anyone to buy into what we are selling--if you aren't confident of the product you are selling, you probably shouldn't be in business.
This is why it makes me happy to see the work 3Scale has done in integrating their own API infrastructure with AWS API infrastructure. You can find the details of the integration opportunity over at 3Scale, but I want to focus on the subject of API service providers working together, even if it is externally augmented like 3Scale did, as opposed to formal partnership.
Within weeks of AWS launching their API Gateway, the 3Scale team was not only unfazed by the potential competition from the cloud giant, they immediately got to work understanding how their own infrastructure could compliment the offering. There is an overlap between the AWS API Gateway, and 3Scale infrastructure, but both platforms bring an immense amount of value to the table, and it is very forward thinking of their team to see this, rather than just sit around worrying about what AWS would do to their business.
3Scale has an eight year head start when it comes to API management, and AWS brings some serious API deployment power to the table with their new Lambda platform. What 3Scale has done, represents how API service providers should behave in the industry. I have lots of experience in trying to get API service providers to work together, and participate in a conversation on stage at events, something that can like getting a group of toddlers to play together.
To me, what 3Scale is doing demonstrate their confidence in the infrastructure they are selling. I saw a number of folks on Twitter highlight what a bad omen it was for API deployment and management service providers, when AWS released their API gateway solution. While it does have significant implications when it comes to the industry, I think the negative impact will be felt by the API service providers who really don't have something of value to offer, and companies like 3Scale who do, will be just fine.
Disclosure: 3Scale is an API Evangelist Partner.
See The Full Blog Post
06 Oct 2015
As I add each API to my stack, I consider security along the way. I require an API key to access all of my APIs using my 3Scale API management infrastructure, and I also have different tiers of access, and while defining this management layer my first impulse is always put POST, PUT, and DELETE methods into the most trusted tiers.
The service composition layer in API management is where I feel the heart of API is--the thing that makes it different than SOA, and other approaches. This is where you can loosen things up, trust your 3rd party developers, and allow serendipity to occur. If you always default to locking things down, and only allowing the updating of resources by internal, or just trusted external sources, you are limiting the possibilities.
With this in mind I'm carefully evaluating a couple of defensive API management tactics I can employ:
- Notifications - Make sure and send out an email or push notification to myself when POST, PUT, and DELETE are executed on certain APIs.
- Key Locking - Allow for a certain amount of POST, PUT, and DELETE, but when you go over a certain volume, it locks your API key.
While these tactics won't prevent all bad situations, it can help me quickly identify them, and take action. My goal is to encourage people to develop on top of my APIs, and I'd rather focus on letting things flow, over locking everything down. There are certain security realities surrounding publicly available APIs, but honestly most people will never take the time to register for key, and learn a system just so they can do malicious things, and for the ones that will, I have some defensive things in place to trip them up.
There are plenty of tools built into my 3Scale API infrastructure that do this for me, what I am considering are some additional measures I can build into my own API, that employ the 3Scale API to better automate some of these defensive tactics. What are you doing to keep things safe, but also open? I'd love to hear other ideas for operating an API on the open Internet, in the safest, most sensible way.
Disclosure: 3Scale is an API Evangelist partner.
See The Full Blog Post
06 Oct 2015
I've been getting demos of some pretty interesting new work spaces meant for API architects, and designers. Examples of this are API Garage, RepreZen API Studio, and the recent SwaggerHub. These are just some of the API life-cycle solutions I'm seeing emerge recently, where companies are trying to provide API design, development, and deployment solutions in a single, tidy, work space.
Now that the API life-cycle has expanded beyond just API management, deployment, and design, into testing, monitoring, security, and beyond, I predict these types of API work-spaces that span multiple stops along the API life-cycle will become common place. To help prime the pump, and ensure there will be more viable products launched, I wanted to share a few thoughts on what these solution providers should consider as part of their offerings.
Here are some of my scribbles while drinking an IPA at my local bar:
- API Definitions - Speak Swagger, API Blueprint, Postman Collections, and other common API definition formats, and allow for the importing and exporting of them at every step.
- Provide APIs - Make sure you provide APIs to all the functionality available within the workspace -- paying the whole API thing forward.
- Consume APIs - Make sure you allow the consumption of APIs, from within the interface, either as part of http client, or add-ons.
- Plug-in Framework - Allow some sort of extensibility of the work space, allowing 3rd parties to augment the platform via plugins.
- Play Well With Others - Please play nice with other service providers, all of this works because of interoperability, and I should be able to use the services I need via my work space.
- Search - Provide a comprehensive search, allowing me to discovery across everything I do within a work space, via a comprehensive history
- Notebook - Give me a notebook for storing my work, draft APIs, and other items I gather through my work, allowing me to come back and re-use work from the past.
- Use Github - Make sure Github is a first class citizen within the workspace, allowing me to import, and publish all my work to Github -- think orchestration, not just import and publish.
- Non-Developer Friendly - Make sure tht the work space isn't just for developers, and anyone can come in and participate throughout the API life-cycle.
- Provide a HTTP Client - Make sure there is a built-in, or embeddable HTTP client, so get building one, partner with existing, or acquire one you like.
These are just a few of my thoughts as I received a demo of one API work space, and was reading about a couple of other new products. After scribbling these thoughts, I sat back, drank a another pint of IPA, and contemplated the role of these types of work spaces in the future of the API industry. I predict there will be a wave of these API work spaces emerge in coming months, providing their own take on exactly what the API life-cycle looks like, and want to help developers standardize and be successful.
I am looking forward to playing with all the new work space, and hoping there will be at least one to emerge that suits my unique needs as the API Evangelist. I will need all of the elements listed above, or I probably won't be working in there full-time.
See The Full Blog Post
02 Oct 2015
I received a personal demo of the new SwaggerHub from Mr. Swagger himself -- Tony Tam, this last week. SwaggerHub is a new API life-cycle hub, centered around the API definition format, developed by the SmartBear Swagger team. The new hub brings together all of the Swagger tooling into a single, collaborative web application, that allows you to manage API definitions through varioius stages of the API life-cycle.
SwaggerHub lets you import and export your JSON or YAML Swagger definitions, giving you an environment for storing, searching, versioning, and collaborating around the definitions. Using the platform, you can edit Swagger definitions using Swagger Editor, generate server and client side code with Swagger CodeGen, and play with the API using Swagger UI--all wrapped in this new versioned and collaborative API design environment.
After importing a handful of my APIs into SwaggerHub, it feels like a solution to help me manage the central truth that are my API definitions, allowing me to bring other people into the process, and generate the code and docs that will be needed at other stops along the API life-cycle. I'm assuming that other stops like testing, monitoring, and virtualization will emerge in future iterations of SwaggerHub.
SwaggerHub works well for API definition centralization, collaboration, and management, but some of the publishing of docs, server and client code didn't work as I'd expect them. There is Github integration for logging into SwaggerHub, and a "Github Push" feature, which I couldn't get to work, so I'm assuming the publishing and orchestration around APIs will only improve -- something I'm really interested in, because I use Github to manage all aspects of APIs life-cycle.
I like what I see so far in the SwaggerHub, and see hints of the future with Docker image references, an API behind the platform, and I know there is APIs.json goodness right behind the surface. For now, I will just keep importing my designs into SwaggerHub, keep playing with, and seeing where Tony and the team takes the new API collaboration destination.
See The Full Blog Post
29 Sep 2015
This is a review of the communication API platform CallFire, crafting a snapshot of platform operations, from an external viewpoint, providing the CallFire platform team with a fresh take on their API from the outside-in. The criteria applied in this review is gathered from looking at the API operations across thousands of API providers, and aggregating best practices, into a single, distilled review process.
This review has been commissioned by CallFire, but as anyone who's paid me for a review knows, money doesn't equal a favorable review—I tell it like I see it. My objective is to help CallFire see their platform through a different sense, as developers might see their platform. It can be hard to see the forest for the trees, and I find the API review is a great way to help API providers see the bigger picture.
I prefer to share my API reviews in a narrative format, walking through each of the important aspect of API management, telling the story of what I see, and what I don't see. Here is the story of what I found while reviewing the communication API platform for CallFire.
CallFire makes for an easier review than some API operations, because the API is the product. As soon as you land on the homepage of the website, you begin your API journey as a potential API consumer. The first thing you read is "Over 2 Billion Messages Delivered”, so you immediately understand what CallFire does, and the next thing that grabs your eye is “Signup For Free”—way to not miss a beat, CallFire.
Next you see five simple icons, with simple text, breaking what CallFire does down: Text Messaging, Call Tracking, Video Broadcast, Cloud Call Center, IVR. Within the first five seconds you fully understand what is being offered, and given the opportunity to sign up. If that is not enough, you are also told the reasons why: Engage Your Customers, Save Valuable Time, Increase Revenue.
After you look at thousands of APIs, nothing is more frustrating than to have to figure out what an API does. CallFire gives me what I need, in five seconds or less, without clicking or scrolling. This is the way all APIs should be, if not the homepage of website, then the landing page of the API developer portal. The main page of the CallFire website is well designed, and organized in a simple, and robust way, giving you one-click access to everything you need to get going with the platform--no other feedback required.
This is the part of the review I dive into the actual design of the API, and provide some feedback on the technical endpoints of the APIs themselves. CallFire is unique because it has a REST and a SOAP version of the API available, which I think is important in today's business climate, where APIs are targeting open developers, as well as those within the enterprise.
The CallFire API is very robust, with wide range of endpoints / methods for the most basic text and call features, all the way up to campaign, subscription, and contact management. You can tell the system is well thought out, providing a full suite of communication resources for all types of developers.
On you dig into the REST API you begin to see quite a bit of SOAP residue, and while the API has a well thought out list of endpoints, many elements of the parameters, requests, and responses feel SOAPy, including the XML responses. There is also a lack of consistent response codes, and defined data model, giving the REST API an unfinished, empty bottom feeling.
Overall I give the API a solid B in that it is a very robust stack, but I'd say it needs some hard use, and integrations before some of the rough edges are hammered off, parameters become more intuitive, and request and response structures normalize. Much of this just comes with usage, and requires getting closer to real world use cases, end users, before it becomes more of an experience based design vs. the resource based design it currently is.
I could easily go through the entire Swagger definition for CallFire and make recommendations on naming conventions, and help craft the resource definitions for the underlying data models, but this is best worked out with the community, iterating, and communicating with developers, and learning more about truly what they need. Think of it as kiln firing of the API, through developer execution, and robust platform feedback loops.
On-boarding with the CallFire API was frictionless. I went one click from home page, authenticated with my Google Account, and immediately I was dropped into my account dashboard, with a helpful intro screen showing me where things are. I easily found the area in my account to add an application, and get my API keys, then stumbled into the overview of how to activate your account as well—account management was intuitive.
The intuitive and informative CallFire home page made the API easy to find, and with frictionless account signup, and a standard API app management, I was ready to make my first call on the API within 10 minutes. The only thing I would consider adding as part of the process, is an option for signup and login using my Github credentials, in addition to Facebook, and Google.
On-boarding with an API is often the most frustrating part of API integration, and it wasn't something I worried about at all with CallFire. The process was intuitive, smooth, and didn't leave me trying to understand what the API does, and how I am supposed to make it work. Solid A on the on-boarding process for the CallFire API.
Documentation is one of the most critical aspects of API integration, making or breaking many integration efforts by developers. CallFire has double duty, in that it needs to provide documentation for the REST and SOAP version. Somethig CallFire manages to deliver with no problem, providing clean, easy to follow documentation for both APIs they offer.
The SOAP API document provides a simple breakdown of operations and methods, with easy to follow descriptions for everything. Ultimately the SDKs do most of the heavy lifting here, but the SOAP docs provide a nice overview of the CallFire platform.
The REST API for CallFire is defined using the machine readable API definition format Swagger, and uses Swagger UI to generate documentation, making learning about the API more interactive. Swagger provides a machine readable overview of the CallFire API, and is an approach to delivering API documentation that keeps pace with modern approaches.
I do not have much feedback for the documentation side of CallFire, I'd like to see more information about the underlying data model described in the Swagger definition, as well more detail about the response codes, but I give the platform documentation a solid B for being simple, clean, and complete--the API just needs some hardening, and the documentation will improve.
On-boarding with the CallFire API is frictionless, and adding an app, and finding your API keys are intuitive enough. The platform also provides a nice overview on how to enable the API on your CallFire account, but ultimately the topic of authentication is neglected.
Authentication for SOAP interactions, and REST for that matter, are abstracted away by each of the SDKs. However one of the elements of RESTful APIs is that authentication should be clearly defined as part of the documentation. I suggest adding a page, or section on an existing page that is dedicated authentication, explaining the BasicAuth used to secure the CallFire API. For any experienced API consumer it isn't difficult navigate, but the app manager with login and password, has appearance that it may be app key via a header or parameter, not BasicAuth--a dedicated authentication overview page would help clear up.
As part of authentication review I do not usually advocate for a specific authentication approach, when the choices are BasicAuth, or using the app id and keys in the header or parameters. The best option is to pick one, be consistent, and explain it clearly, on a page that stands out. Overall the authentication for CallFire is intuitive, it just needs a little bit of information to makes things 100% clear when you first find yourself making that first API call.
UPDATE: Since I wrote this review, and the time of publishing, CallFire has updated their portal to include a well formed authentication overview for the platform.
After documentation, code samples, libraries, and SDKs are key to a painless API integration. For the CallFire API, there are only two SDKs available currently, for the PHP, and .NET platforms. It is common that platforms who are just getting going, only have a handful of SDKs in specific language, and is forgivable, but is also a sign of platform immaturity (aka lots of work still to be done).
Another aspect of SDK design for CallFire, that I'd like to bring up, is the cohabitation of REST and SOAP in a single SDK. I'm not sure this type of cross pollination is ideal for all integrations. Maybe it is just my architectural style, but I like seeing each SDK be as smallest possible footprint as possible, and meet the needs of developers without any extraneous bloat.
Moving beyond SDKs, into what I call Platform Development Kits (PDK), CallFire does well in providing two distinct platform plugins for WordPress and Drupal. I recommend bringing these PDKs to the surface, and showcase them in a full SDK and PDK showcase page—showing what is possible. Maybe even considering the next step, of what is the 3rd PDK that could be developed? SalesForce? Heroku?
The usage of Github by CallFire is another important signal, showing the platform is progressive, and something that developers can depend on. I recommend further bringing Github into the site, linking to accounts, providing direct links to SDK and PDK repositories from an official page, and add Github authentication for developers to be able to create and manage their accounts. Github isn't just about code, it is a potentially important social layer to the CallFire API ecosystem.
There really is no evidence of any mobile SDKs, or information for mobile developers available on the CallFire platform. It is common to find entire sections dedicated to mobile developers, or at least links to mobile platform specific code libraries. I recommend establishing a mobile focused section of the platform, and invest the resources necessary to help developers build iOS, Android, and Windows mobile applications using CallFire.
CallFire is doing well on the support front, providing building blocks for both direct, and self-service support. I like to see a mix of support services that developers can find on their own, getting the help they need 24/7, but they also need to be able to get direct support when they get stuck.
When it comes to direct support, CallFire is rocking it, with a support email, live chat, phone number, contact form, and ticketing system tied to your account messaging area. The only additional things I could recommend CallFire offering is paid support plans, allowing developers to pay for one-on-one support via chat, online hangout, or other means.
With self-service support, there is the CallFire FAQ, which I'd call more a knowledgeable than a simple FAQ, providing a wealth of knowledge about the platform. The only common element I see missing is more of a community element with a forum, or usage of Stack Overflow to engage with the wider developer community. The current FAQ is very robust, and with the integrated ticketing system, the potential is great, but it is all missing that community piece.
Overall, CallFire support is as robust as you'd expect from any API platform. When you combine with the social media presence the platform has, that I'll cover as part of the communication strategy, the platform has all of its bases covered. A+ on support effort.
When it comes to my review criteria for communications, other than a newsletter, CallFire nailed everyone of them. The platform has all of the expected social media platforms, has an active blog with RSS feed, and is very accessible with email, phone, and chat. All of this sends the right signals to the community, and potential API consumers, that someone is home. I have nothing to contribute when it comes to communications, as long as all channels are kept active, CallFire is doing everything it can in my mind.
As platform providers, we are asking developers to depend on us, and integrate our resources into their applications, and businesses. That is asking a lot, and we need to provide as much information as possible about what the future hold, to hlep build trust with developers. There a handful of proven ways for doing this, established by leading API platforms.
- Roadmap - API roadmaps are usually a simple, bulleted list, derived from the APIs own internal roadmap, showing what the future holds for the platform. Transparency around an APIs roadmap is a tough balance, since you don't want to give away too much, alerting your competitors, but your developer ecosystem needs to know what is next.
- Status Dashboard - Status dashboards are a common way for API platforms to communicate the availability of an API, but also show the track record of a platform, helping developers understand the track record for an API they are to integrate with. There are several simple services, that help API providers do this, without investment in new tools and systems.
- Change Log - Knowing the past is a big part of understanding where things are in store for the future. A change log should work in sync with the API roadmap building block, but provide much more detailed information about changes that have occurred with an API. Developers will not always pay attention to announced updates, but can use a change log as a guide for deciding what changes they need to make in their applications and how they will use an API.
Sharing the change history of a platform, a roadmap to the future, and a status of API operations at the moment go a long way in help build trust with developers. Transparency in the development of any platform, is essential in helping developers feel comfortable that a platform will be around to support their needs, and is worthy of their time.
When reviewing APIs, the overall business model is usually one of the most incomplete aspects of operations, in my experience. This is ok, as many platforms are still figuring this out, however this is not the case with CallFire. The business model for the platform isn't just well defined, it provides me with an example to use when helping other API providers visualize what is possible.
The pricing page for CallFire is clean, well thought out, and provides sensibles tiers of operation, with clear units of measurement, letting me know what I get for each level. I can easily upgrade the access tier directly from my account settings, and I can get volume pricing if needed. This is how APIs should work, allowing me to easily calculate what I'll need, and figure out which tier I will be operating within, complete with a self-service option for scaling as I need, paying for what I use, as I go.
The billing management and credit system for CallFire is superior to most of even the most thought out API billing and pricing models. It is clean, well thought out, and makes sense from a user perspective—which is the most important aspect. I'll be using CallFire credit system as a reference when I talk about how the platforms should build tooling that supports the underlying API business model.
I can't articulate enough, how well done the business model, pricing, supporting billing and the other business elements of the CallFire API.
When it comes to available support resources, it is another area CallFire does very well. The platform has heavily invested in case studies, videos, webinars, and a tour of the platform. They even have a communications and marketing glossary developers can use to get up to speed. CallFire does a good job of providing valuable resources to get developers quickly understand all aspects of platform operations..
A couple of areas I could provide suggestions for improvement, in is when it comes to more industry level white papers, and when the evangelism side of things kicks in maybe consider posting slide decks from events CallFire presents at, as well as a calendar of interesting events. These things will happen I'm sure once an API evangelism strategy is kicked into full gear, but for now just keep doing more of the same--providing lots of rich resources for devs.
Research & Development
I'd file R&D in the same category as mobile, non-existent. API ecosystem are essentially external R&D labels for companies, and general operations are about exploring ideas of what can be build with an API, but it helps to have some element available to stimulate overall R&D via the platform.
Some of these elements are:
- Idea Showcase - A place the community can share ideas of what could be built with the CallFire platform.
- Labs Environment - A workbench showing what CallFire is working on when it comes to their own integration.
- Opportunities - Available opportunities to build things like SDKs, PDKs, or specific projects.
These are just three things that help stimulate the innovation around an API. Sometimes developers just need something to spark the imagination, or possibly see an existing labs project to help them see something in their own work. These rich R&D environments can provide a great opportunity to help meet the needs of CallFire, and its partners.
A couple of items I'd recommend also considering, based upon what I seen on other platforms:
- Code License - The PHP SDK has an MIT license, but the .NET didn't have anything. A centralized code licensing page could help as well.
- API License - A license for the API itself, applied to the REST API interface that is defined by Swagger, using API Commons format.
- Service Level Agreement (SLA) - Provide a service level agreement for API consumers to take advantage of, and understand service level commitments.
- Branding - There are no branding or style guidelines with support resources like logos, etc—missed opportunity for spreading word, and steering developers in the right direction.
Just a couple of things to think about. All of these would go a long way in building trust with developers, and the branding thing is a huge missed opportunity in my opinion. When you bundle these with the TOS, privacy, and compliance information already provided by the platform, it would round off the legal department of the CallFire API nicely.
Embeddable tooling is another area that is non-existent for the CallFire API. There are no embeddable tools like widgets, buttons, etc that allow the average end-user, and developer to put the API to use in web pages, and applications. I'm not sure what an embeddable suite of tools would look like for CallFire, that would need to be a separate brainstorming process.
When it comes to communication platforms, especially ones involving media, and deep social interactions, embeddable tools are a proven way to grow platform, expand the network effect, and potentially bring in new developers. I recommend including an embeddable section to the site, with a handful of embeddable tooling to compliment the SDK and PDK resources already available.
One area I consider when looking through API operations, is the environment itself. By default many APIs are live, ready for production use, but increasingly platforms are employing alternate environments for development, QA, and potentially variant product environment.
- Sandbox - With the sensitive information available via many APIs, providing developers a sandbox environment to develop and test their code might be wise idea. Sandboxes environments will increase the overall cost of an API deployment, but can reduce headaches for developers and can significantly reduce support overhead. Consider the value of a sandbox when planning an API.
- Production - When planning an API, consider if all deployments need to have access to live data in real-time or there is the need to require developers to request for separate production access for their API applications. In line with the sandbox building block, a separate API production environment can make for a much healthier API ecosystem.
- Simulator - Providing an environment where developers can find existing profiles, templates or other collections of data, as well as sequence for simulating a particular experience via an API platform. While this is emerging as critical building block for Internet of Thing APIs, it is something other API providers have been doing to help onboard new users.
- Templates - Predefined templates of operation, when a new environment is setup, either sandbox, production, or simulator, it can be pre-populated with data, and other configuration, making it more useful to developers. These templates can be used throughout the API lifecycle from development, QA, all the way to simulation.
This approach to delivering an environment for the CallFire API is not essential, but I could see it providing some interesting scenarios for communication campaigns, and the deployment of messaging infrastructure in a containerized, Internet of Things rich environment. Deployment CallFire communication infrastructure should be as flexible as possible to support the next generation of Internet enabled communication, both in the cloud and on-premise.
An often overlooked aspect of API operations is the tools provided to API consumers. CallFire is in a fortunate position as the API is core to their product, and the API integration is an extension of a primary CallFire user account. The account area for CallFire is well done, clean, and gives users, and those who choose to be API consumers, quite a bit of control over their communication infrastructure.
CallFire nailed almost every API account area I like to see in any API platform:
- Account Dashboard - The dashboard for CallFire account is well done, and information.
- Account Settings - CallFire provides a high level of control over account settings.
- Reset Password - Resetting password is important, and I like to highlight separately.
- Applications - The app management for CallFire is on par with rest of industry.
- Service Tiers - The ability to change service tier, and scale is pretty significant.
- Messaging - An import part of the communication and support strategy of platform.
- Billing - Essential to the economy portion of platform operations, well executed.
There are a couple of areas I'd like to see, to round off developer account operations:
- Github Authentication - It would fit nicely with Facebook, and Google Auth--I prefer authenticating for APIs with my Github.
- Delete Account - Maybe it is in there, but I couldn't find it. The ability to delete an account is important in my book.
- Usage Logs & Analytics - I'd like to see application specific analytics like on the dashboard, showing usage per app.
- Account API - Allow API access to all account operations, allowing access to account settings, usage limits, billing, messaging and other areas.
The CallFire account management for users and developers is much more robust than I see in many of the APIs I review. Like I said before the monetization portion is something to be showcased, and all the most important aspects of account management for API operations are present. It wouldn't take much to round off with a couple more features, some more analytics, and an account management API would really take things to the next level.
I always enjoy when I come find consistent design, and function across API operations. This is what I found with CallFire. The API isn't an afterthought like other platforms, it is their product, and the site design, messaging, and content are consistent across the platform.
The API design is consistent, and the supporting documentation is as well. The only thing I'd add is design patterns across the SOAP and REST API should be less consistent, and stay true to their own design constraints. The details of the REST could be tightened, to be more consistent in how parameters are formed, and response formats, and error code are commonly presented.
Usually when reviewing APIs, I look for fractures between API operations, like clunky UI between website sections, or incomplete documentation, often created by disparate teams. This doesn't exist with CallFire, and while there are many details that could be cleaned up, the consistency is all there.
This is a term thrown around a lot in the space, and very seldom do sites live up to it. There are many things that contribute to whether or not an API is truly open. CallFire delivers on all of the important areas, making open a word I'd apply to CallFire.
One of the things I think heavily contribute to the openness of the CallFire platform is the business model. The monetization strategy is well formed, with pricing and service tiers well defined. You know what things cost, and how to get what you need. This type of approach eliminates the need for other extraneous rate list, or restrictions—this type of balance is important to truly achieving openness.
After this review I'd call CallFire an open API, but only time will tell, if the platform is also stable, support channels are truly supportive, and other aspects of open that only CallFire can deliver on. For right now I consider them open for business, and open for developers, but ultimately whether or not CallFire is willing to share this review, will put the exclamation on the platform openness definition, won't it! ;-)
The usual footprint you'd see when an API platform has an active evangelism program doesn't exist for CallFire, but that is part of the motivation of this review. We are looking to take a snapshot of where the platform is at, in hopes of providing much needed input for the roadmap, as well as establish a version 1.0 evangelism strategy--we will revisit the evangelism portion of this review in a couple months.
In short, the CallFire passes my review. There are several key areas like mobile, and roadmap communication, that are missing from the platform entirely, but then there are other areas CallFire nails almost every one of my review criteria. The API is robust, the documentation is complete, and they provide all the essential support building blocks.
One of the things that really stand out for me is the CallFire business model, something that I think really cuts through the BS of many APIs I look at. CallFire has a clear business model, and the tools to manage your API usage. There is no grey area with the business of model for CallFire, which is something I just don't see a lot of.
I'd say my biggest concern with the platform is the lack of diverse code resources. I can't tell if they are just getting going, or maybe the lack of developer skills is slowing the diversity of available coding resources--I am just not sure. My guess is their is a lack of diverse developer skills on staff, which explains the lack of mobile SDKs, and the SOAP residue on the REST API. My advice is to invest in the developer resources necessary to load the platform up with a wide variety of coding resources that developers can put to work in their projects.
Beyond the code resources, it is really just a bunch smaller items that would bring the platform into better form. CallFire definitely reflects everything I'm looking for in an API platform, and is something I've included in the top APIs I track on as part of my API Stack. Additionally, I've gathered a couple of other stories while doing this review, including the overall monetization strategy, the notification system under account settings, and their usage of Swagger—which is always another good sign of a healthy platform, and a positive review.
Lots going on with the CallFire platform, I recommend taking a look at what they are up to.
This was a paid review of the CallFire platform, if you'd like to schedule a review of your platform, please contact me, and we'll see if I can make time. A paid review does not equal a good review. it is my goal to give as critical, and constructive feedback as I can to help API providers enhance their roadmap and better serve their consumers.
See The Full Blog Post
26 Sep 2015
I have a whole bunch of APIs I want to deploy. There is a queue of APIs that I will never get to, but I can't help myself, and when I am tired of watching what everyone else is doing, and want to get busy actually building things, I crack open my queue of ideas. This weekend I launched four new APIs, that will be in the service of some very different objectives that I have.
- Low Hanging Fruit - Identifying the potential CSV, XLS, XML, and table resources that exist in any domain, and publish them to Github as a list for deploying as APIs - aka the low hanging fruit.
- TSA.Report - A simple form for submitting your thoughts as you are going through the airport line.
- APIs.How - The URL shoretner for the API Evangelist and Kin Lane network--getting off Bitly.
- Magnetic Jargon - A dictionary creation API, allowing the building of word lists to use for a magnetic fridge web and mobile app I am building.
Each of these APIs have a specific purpose. Low Hanging Fruit, and APIs.how are both very back-end system tools, where TSA.Report and Magnetic Jargon are meant to drive simple web and mobile applications. The purpose of these applications are not the point of this story, the minimum viable existence of these four new APis is what I want to talk about.
These four APIs are far from complete. I anticipate that TSA.Report and Magnetic.Jargon will evolve based upon the apps that are developed on them, but Low Hanging Fruit and APIs.How are core to how I do business, and will continue to evolve as far as I can afford to scale them (ie how many sites and links I can index).
My goal this weekend, is to just get the APIs up and running. Their overall relevance and productivity in my world will be decided by their roadmap. I just needed to establish them as a real project, and get a mimum viable definition up and running. Here is what defines a minimum viable API in my world right now:
- API - One or many endpoints that serve data, content, or other resources via one of my domains.
- Swagger - A JSON definition of the surface area, and underlying data model for any API I provide.
- API Blueprint - A markdown definition of the surface area, and underlying data model for any API I provide.
- Postman - A Postman Collection allowing anyone to quickly deploy an API in a Postman Client.
- API Science Monitor - At least one monitor of one of the endpoints, acknowledging it is up and running.
- APIs.json - Providing an index of each project, giving me machine readable access to each API, as well as its operations.
- Github Repo - A repository to house the server code (privately), but also publish a developer portal with API definitions available via a known location.
This the current minimum viable definition of an API in my world currently. I will be adding more endpoints to each of these APIs, as well as other building blocks to support their operations, but this represents the start for each of these projects for me.
Honestly I do not know if each of these APIs will survive. They will each have their own road-maps, one that is driven based upon how much I evangelize, and ultimately attract interest from consumers. Each API will have its own monetization strategy, something I will work on sharing via the API definitions that I've published in their API portals.
Two of these APIs are core to my operations as API Evangelist, while two of them are just really for fun, and are in support of simple micro apps I wish to deploy. Low Hanging Fruit will depend on how much funding I can get for each domain indexes, and APIs.How will thrive based upon the growth of my own writing and storytelling. The other two will be driven by advertising revenue, and I do not expect anyone to actually build anything else on the APIs, they only exist because I am API-first in everything I do.
Now that I have a minimum viable existence for all four of these APIs I can move into the next next steps for each project, while also addressing other items on my task list, but at least I know these projects are up and running, and discoverable when I get time to get back to them.
See The Full Blog Post
24 Sep 2015
I was gathering my thoughts today around API management solutions can better work together, in response to an industry discussion going on between several creators of open source tooling. The Github thread is focused on proxies, and how they can work more closely together to facilitate interoperability in this potentially federated layer of the API economy, but as I do, I wanted to step back and look at bigger picture before I responded.
As I was gathering my thoughts, I also had an interesting conversation with the creator of API Garage, in which one of the topics was around how we encourage API service providers to want to work closer, but this time from the perspective of a API client workspace. This made me think, that the thoughts I was gathering about how open source proxies can better work together, should be universally applied to every step along the API lifecycle.
It should be a no-brainer for API service providers--have an API! One of the best examples of this, is with 3Scale API management--they have a very robust API, that represents every aspect of the API management layer. Other service providers like API Science, and APIMATIC, who server other stops along the API life-cycle, also have their own APIs. If you want your API tooling to work with other API tooling, have an API--think about Docker, and their API interface, and make your tools behave this way.
Provide openly licensed tooling around any service you provide. Make your tooling as modular as you can, and apply open source licenses wherever it makes sense. Open licenses, facilitate people working together, and breaks down silos. This is obvious to the folks on the API proxy thread I'm referencing, but will not be as obvious to other service providers looking to break into the market.
Speak common API definition formats like Swagger, API Blueprint, and in Postman Collections, and provide indexes using APIs.json. If consumers can import and export in their preferred definition format they will be able to get up and running much quicker, share patterns between the various proprietary services, and the open tooling they are putting to work. There are a lot of opportunities to partner around common API definitions for API deployment, and management, which would open up a potentially new world of API services that aggregate, integrate, and sync between common API platforms throughout the life-cycle.
Developers never want their tooling to be a silo. Allow the extensibility of any tooling or services, from design, to management, or client, using common approaches to connectors, plugins, etc. Make plugins be API first, so that other API service providers can easily take their own APIs, craft a plugin, and quickly bring their value to another platform's ecosystem. Plugins are the doorway to the interoperability that open APIs, source code, and definitions bring to the table for platform providers.
Open APIs, source code, definitions, and plugins all set the stage for ever deeper levels of partnership. APIs are the pipes, with open source code and definitions providing the grease, and if all API design, deployment, management, monitoring, testing, performance, security, virtualization, and discovery providers allow for plugins, strategic partners can occur organically.
All of this really sounds familiar? It really sounds like what the API space is telling the rest of the business world, so I can't help but see the irony in giving API service and tooling providers this same advice. If you want more partnerships to happen, expose all your resources as APIs, providing open tooling and definitions, allow other companies to plug their features into your solutions, and a whole new world of business development will emerge.
With the mainstream growth we are seeing in the API space in 2015, there are some pretty significant opportunities for partnership between API service providers right now--that is, if we follow the same API-first approach, currently being recommended to API providers.
See The Full Blog Post