API Providers Guide - API Management

Prepared By Kin Lane

July 2014

API Providers Guide - API Management

Table of Contents


Overview API Management

API management was not born out of any particular group or standard, it was defined by the early API pioneers like SalesForce, Amazon and Ebay, and iterated upon by other newcomers like Twilio, SendGrid and others.  

As a standard offering, the first startup to offer API management as a service was Mashery in 2006, who helped set a common approach to providing API portals and coined the term business of APIs.

In 2014 there are over 20 API management service providers providing a wide range of services from access management and analytics to complete API gateway services to help you deploy and manage hundreds or thousands of APIs from internal resources.

I've always lumped everything about providing APIs into a bucket called API management. I'm slowly pulling out the separate pieces like design, deployment, monetization and evanelism, leaving API management as the technology, business and politics of managing multiple APIs for your company, or as a business.

There are two main paths that API providers take, either DIY approach where you have the resources and launch your own portal, and cobble together various tools and services to make it all work. The second path is talking to several of the API management providers and discovering which one will best help you with your goals.

Whichever path is taken, the goal of this paper is to provide you with the building blocks and overall knowledge you will need to be successful. I have studied the tools and services offered by the API management service providers, but more importantly I have looked at all the public APIs available today, and tried to reflect the best practices they've established through operations.

API management will include a portal area, where you host the operations of one or many API resources, as well as multiple public platforms like Stack Exchange and Github.  API management involves not just the management of the technical API interfaces, but the blog, forums, documentation, support desk and other critical building blocks of API operations.

Any company or individual that is new to the game, I highly recomend spending 2 weeks studying the top API platforms and understanding how they run their own API management operations. Next I recommend you pick 2-3 of the API management service providers and give them a call, have conversations with them about your goals.  

API management is not something you read the book on, then execute flawlessly. API management is about ongoing, iterative research and development around your companies data and resources. Your API management strategy will define the next phase of your business development.


Building Blocks

At API Evangelist I define things in terms of building blocks, meant to establish, easy to understand modules you can pick and choose from as part of any strategy, including API management.  

In 2010 I started API Evangelist as a research project to look at how the top 250 popular APIs were doing business. I spent the summer of 2010 looking at these API providers and established a list of building blocks I found each provider using to manage their API operations.

I've been maintaining this list for 3 years now, looking at over 9,000 APIs and assessing the building blocks used by the top 2,000 APIs. I've tried to standardize these and establish a potential list that any API provider could consider when planning their own API management strategy.

These are the most common examples of API management building blocks.

  • Onboarding
    • Best Practices - An API delivers access to a business's valuable resources, and no doubt there will a level of conduct that will be expected of developers while accessing these resources. While a developer is onboarding, this is the best time to provide a plain english introduction to the best practices around integrating with an API. Best practices should be an introductory lesson for developers of how to properly integrate with an API, it should not dive into the legaleze and granular detail provided by terms of use. Think of your best practices as a more friendlier, and easier to follow version of your terms of use--setting the proper tone of how a developer will use APIs as they are getting started.
    • FAQ - FAQs are a standard in many online platforms, not just APIs. API owners will know what the common questions developers ask when onboarding with an API, or learning advanced concepts. These questions, with relevant answers need to be published where developers can quickly find them. An FAQ building block is a great way to address these questions in a self-service way--make sure and keep the page a living document, adding new questions received through other support channels, as well as keeping older questions fresh.
    • Getting Started - API integration. Developer onboarding is dependent on laying out simple, clear steps for developers on how to register, authenticate, access documentation and code samples, get support and any other details that are essential to API integration. A quality getting started guide should be easily accessed from the API landing page, and kept simple. Try to only provide what a developer needs to get started with as few possible steps as possible. The getting started will not just make developer onboarding frictionless, it will speed up onboarding, increasing the chance a developer’s successful integration.
    • Self-Service Registration - You’ve launched an API to stimulate innovation around your company's resources. Don’t stand in the way of developers innovating. Provide self-service registration for developers to gain access. Even if an API is not meant to be public, there are plenty of ways to provide self-service access while still securing the API--such as using invitation codes or limited entry service tiers, that limit access when developers first register. Innovation around an API will occur around the clock, don’t make developers wait for access. Another area to consider when trying to reduce friction during registration, is allowing developers to register using their existing social network accounts like Twitter, Facebook and Google. When employing this option, make sure and include Github, which is the most logical of social networks for developers to use when registering for an API--Github allows the API owner to stay in tune with the profile of a developer that is most relevant to APIs and programming, and not just their everyday social life.
    • Service Accord - Before API consumers commit to using an API they need to uderstand best practices for consuming an API, but they also need to understand what level of service they can expect from a provider. Service level agreements (SLA) provide a legal framework managing the relationships between API consumers, but service accords provide a plain english explanation of what they expect from a provider, without the legaleze, in a format they can understand in five minutes or less, without calling the lawyers.
  • Documentation
    • API Explorer - API explorers allow users to make calls and explore REST APIs using a web interface. The simplicity of REST has contributed to the extreme growth in the number of Web APIs in the last year, and API explorers are going to fuel this growth. API explorers put the power of Web APIs in the hands of non-developers, allowing journalists, students, politicians, and any tech savvy Internet user to access the data and functionality available via APIs.
    • Documentation - Quality API documentation is the gateway to a successful API. API documentation needs to be complete, yet simple--a very difficult balance to achieve. This balance takes work and will take the work of more than one individual on an API development team to make happen. API documentation can be written by developers of the API, but additional edits should be made by developers who were not responsible for deploying the API. As a developer, it’s easy to overlook parameters and other details that developers have made assumptions about.
    • Error Response Codes - Errors are an inevitable part of API integration, and providing not only a robust set of clear and meaningful API error response codes, but a clear listing of these codes for developers to follow and learn from is essential. API errors are directly related to frustration during developer integration, the more friendlier and meaningful they are, the greater the chance a developer will move forward after encountering an error. Put a lot of consideration into your error responses and the documentation that educates developers.
    • Interactive Documentation - There is a new movement in API documentation, one that is moving beyond static, often boring documentation and into a new realm where API documentation is live and interactive. Following in the footsteps of API explorers these new interactive documentation formats like Swagger and Mashery I/O Docs, allow developers to authenticate, navigate endpoints and make requests with live responses returned. In a little over a year, interactive API documentation has gone from a new innovation of a select few APIs, to being a standard offering among many of the leading APIs in the space. There is no better way to get your developers acquainted with an API, than allowing them to interact with your API while reading documentation--turning API documentation into a hands on experience.
    • List of Endpoints - Before a developer is thrown into the full detail of API documentation, it helps to introduce them to all available API endpoints, getting them acquainted with the resources available. A simple listing of all endpoints provides a quick introduction, that will prime developers for a deeper dive. After reviewing all API endpoints a developer can start to imagine how their application will integrate with an API, further understanding the value the API will bring to their application. Sometimes it's hard to see the 100K view of an API from regular documentation, start with just listing the API endpoints.
  • Authentication
    • Authentication Overview - Always provide an overview of what type of authentication is provided for an API. Don’t assume developers will know anything about Basic Auth or oAuth. Walk developers through goals behind authentication, with links to tutorials regarding authentication technology. If an API employs oAuth, make sure and take extra special attention to provide clear instructions on how to use, as well as language specific code as part of your API SDKs. After poor API documentation, oAuth integration is the number one stumbling point for API developers.
    • Authentication Tester - When possible, provide a testing tool for authentication. From key and Basic Auth to oAuth, allow developers to enter their keys or tokens and validate the credentials they are using, to make sure they are using the proper credentials. A simple tester can provide quick validation that they are doing it right or show them where they are making a mistake, eliminating serious frustration while programming.
  • Code
    • Application Gallery - Complete, functioning applications built on an API is the end goal of any API owner. Make sure and showcase all applications that are built on an API using an application showcase or directory. App showcases are a great way to showcase not just applications built by the API owner, but also showcase the successful integrations of ecosystem partners and individual developers. Do not hesitate populating an application showcase with your own active or starter kit applications. As with all of the API code, make sure and provide as liberal licensing as possible to ensure developers can be successful with use.
    • Code Libraries - Working code samples in all the top programming languages are common place in the most successful APIs. Documentation will describe in a general way, how to use an API, but code samples will speak in the specific language of developers. Make sure and provide a wide variety of code samples, not just what the API development team uses. Consider popular web languages like PHP, Python and Ruby as well as lesser languages like ColdFusion and Perl. Make sure and consider enterprise developers with Java, C# and even VisualBasic. Then consider JavaScript and the popular JS platform NodeJS, which will feed into later building blocks of a healthy embeddable strategy. Remember your developers may not speak HTTP and REST, but will speak one of these programming languages fluently, so make code samples as inclusive as possible, reaching the widest possible audience.
    • Cross Platform Mobile Development Tools - One way to address the iOS, Android and HTML5 building blocks all at once is using cross-platform mobile development platforms like PhoneGap and Trigger.io. These platforms provide a suite of mobile development tools that allow developers to build mobile applications that can be deployed as native apps for iOS and Android while also providing mobile web versions. Providing API developers with PhoneGap and / or Trigger.io resources, API owners can rapidly grow the number of mobile apps developed on top of an API, with fewer resources.
    • Github - GitHub is a social coding platform allowing developers to publicly or privately build code repositories and interact with other developers around these repositories--providing the ability to download or fork a repository, as well as contribute back, resulting in a collaborative environment for software development. Github provides an excellent platform for API owners to engage with developers outside of a local API ecosystem. Developers are already actively pushing code and interacting on Github, making it a perfect opportunity for API owners. It is standard practice for API owners to establish Github repositories for all SDKs, starter projects and Platform Development Kits (PDK), as well as deploy Github Gists for actively displaying all code samples. Beyond using Github for pushing code, as stated above in the self-service API registration building block, Github also provides a preferred account integration for API developers to use that provides opportunities for healthy social interactions amongst API ecosystem developers.
    • Open Source - An API is inherently an external part of a company. The documention, code samples, SDKs, starter kits, platform development kits and any code related to an API, should be considered external intellectual property and licensed accordingly. Consider open sourcing all of the code associated with an API. Open source will fuel the innovation that is already present in API ecosystems, further reducing the friction experienced by developers in successfully integrating their applications and businesses with an API.
    • Platform Development Kits (PDK) - In the era of cloud computing there are numerous Platforms as a Service (PaaS) that allow developers to integrate with existing, thriving ecosystems like Facebook or Salesforce. While planning code related building blocks consider these platforms, and the possibility of providing platform specific development kits. Every API that deploys will suffer from a lack of developers. Building Platform Development Kits (PDK) can help an API go from zero users to an active community of developers by embracing these existing providers. There are many different incarnations of these platforms, such as Facebook, Wordpress, Drupal, Salesforce and Heroku--spend the time and get to know which platforms may best suit your API.
    • Software Development Kits - Software Development Kits (SDK) are the next step in providing code for developers, after basic code samples. SDKs are more complete code libraries that usually include authentication and production ready objects, that developers can use after they are more familiar with an API and are ready for integration. Just like with code samples, SDKs should be provided in as many common programming languages as possible. Code samples will help developers understand an API, while SDKs will actually facilitate their integration of an API into their application. When providing SDKs make sure and consider a software licensing that gives your developers as much flexibility as possible in their commercial products.
    • Starter Projects - Many API owners are going beyond just code samples and generic SDKs for their API ecosystems and providing open-source, private label applications built on top of an API that developers can download, modify and deploy. These projects go by many names, but are commonly known as starter kits or projects. Starter kits can act as code samples, and may contain a version of an SDK, but provide a complete application that reflects common integrations with an API. As with samples and SDKs, start kits will speed up integrations, providing developers with the path of least resistance from registration to active API integration.
  • Mobile
    • Android - When it comes to mobile development, Google’s Android platform is definitely the number two player in the space, and warrants similar attention as the iOS building block. Consider providing Java code samples and SDKs specifically for the Android mobile platform. Android is picking up momentum in the space and with new devices being released all the time, API owners can’t ignore the platform as a serious contender.
    • Appery.io - A new breed of mobile development platforms are emerging, and the leader of these is a product called Appery.io, from established technology company Exadel. Using Appery.io developers and even non-developers can build cross-platform mobile applications using a GUI building environment. Appery.io provides a suite of API connectors allowing for rapid mobile application development using APIs, with the ability to then deploy as native iOS and Android as well as web mobile applications. API owners should consider working with Exadel to deploy an API connector for their companies API.
    • HTML5 - While the native app vs. HTML5 app development battle rages on, API owners have to closely pay attention to HTML5 as a viable alternative offering for their API developers, right alongside iOS and Android. For many web developers, HTML5 is a natural transition to mobile development--a factor that may tip the future toward more HTML5 mobile implementations. Big players like Apple, Facebook and Google are investing heavily in the future being HTML5, which sends the signal to API owners, that they should do the same.
    • iOS - The trends is clear. Apple is the dominant platform for mobile application development. API owners need to have a clear understanding of what iOS developers are needing for both iPhone and iPad application development. When possible, provide iOS specific code samples, SDKs and other resources iOS developers can employ to make their API integrations successful.
  • Self-Service Support
    • Forum - Forums have become an essential building block in API communities for self-service support. A well moderated, active forum can evolve an APIs development area into an actual community. All forum communities will require the API owner to engage developers, keeping conversations active and questions answered, but with the right developers your forum can become self regulating--with opportunities for more senior developers to answer the questions of newer, more junior users, providing potentially free resources for an API owner.
    • Stack Exchange - Developers do not always rely on the forum or support of a single API. They have long established their own communities for support across many public APIs, programming languages and platforms. The leading open forum for this developer activity is Stack Exchange.Stack Exchange provides a community for developers of all types to share knowledge and answer questions encountered during development of any type. API owners need to actively monitor and participate in conversations on Stack Exchange and not expect developers to always engage on their own local API forum. Some API ecosystems like Foursquare and Facebook have even migrated their entire forum to a dedicated Stack Exchange forum, in recognition of the value developers put into the Stack Exchange.
  • Direct Support
    • Calendar - An active API will have many events that can be shared with its community, ranging from conferences, hackathons and meetups the API provider will be attending, to industry related events that developers can benefit from. A published calendar is a great way to publicize these events, while also showing that the API is actively engaged within the API community and beyond.
    • Office Hours - Open office hours is a great way to provide direct support for developers, in a controlled and sustainable format for API owners. Many popular APIs post office hours each week, giving developers an open time they can engage with support representatives via Skype, Google Hangouts or sometimes even in person. Consider the possibility of using API open office hours to support an API community.
    • Phone - Much like email, a phone number can be a solid choice for API developer support. Especially if you have a dedicated, partner target audience. Phone can be the instant gratification that developers need when they hit problems, get their questions answered and move forward with their API integration. Not all API providers will have the resources for phone support, but in some circumstances it will do the trick.
    • Ticket System - Providing developers with a support ticketing tool, using a custom system, or via a popular platform like Zendesk, can be the healthy way to support the needs of an API ecosystem. Not all developers will want to publicly post their problems, and support tickets can be a very organized way to handle the direct support needs of developers, allowing API owners to respond quickly to easy questions, but also allowing them to organize larger scope items into lists that can be used in API product development, providing a direct link between developer support and the API roadmap.
  • Communications
    • Blog w/ RSS Feeds - An active blog can provide a quality SEO presence for an API, attracting developers and businesses to the API. Secondarily a blog can provide essentials communications for the developer community. While researching this white paper and reviewing 6000+ APIs, a blog is the number one way I could tell when an API is dead and nobody is supporting the community. A blog can easily provide the communication to keep an API active and growing, while also be the barometer of whether developers should steer clear of an API. Make sure when deploying a blog, you don't forget the RSS feed!
    • Email - Sometimes your API building blocks are not complex tools or documentation. They can be as simple as an email address. Of course simply listing an email address as part of your API community is not where it ends. Don't list an email for developers, partners, or support if nobody answers it. Make sure and have a plan for any email addresses you use throughout your API community. Make them meaningful and route to the right people. Make sure your email accounts are responsive, otherwise people will immediately go to your forums with negative feedback. Consider an email account to provide support for your API community.
    • Email Newsletter - An email newsletter is a proven communication tool beyond APIs, and while many developers will not be open to receiving regular emails about an API, there are some developers who are still receptive to this format. As an API owner, there is also a positive effect from having to gather thoughts each week for an email newsletter that goes beyond just communicating with the developer community.
    • Facebook - Like LinkedIn, Facebook carries a great deal of social weight when it comes to working with developers. Depending on your target developer audience, Facebook may or may not make sense as part of your communication strategy. Facebook is larger than just the individual social network accounts, and a Facebook Page can be a great way for API owners to attract and engage with developers who are building applications. Consider the Facebook effect when assembling API communication building blocks.
    • Google+ - While Google+ is not as popular as Twitter or Facebook, it does have as many active users as LinkedIn these days, and with considerable SEO benefits, it is recommended that you consider Google’s social network as one of the API communication building blocks. Google+ has a tremendous amount of network effects beyond just the social network and Google SEO. Tools like Google Hangouts can be used as part of API open office hours, and events can be used to coordinate API focused gatherings.
    • LinkedIn - LinkedIn is a powerful business communications platform. While LinkedIn is not the preferred platform of many open API developers, it is the preferred platform of enterprise developers. As an API communications building block, an active presence on LinkedIn is recommended for API owners, it can add a healthy dimension to your communication strategy and reach older, more established developers that may not always be considered when deploying public APIs.
    • Twitter - Twitter as a communication platform, much like a blog is a great way to establish an active presence for an API, providing updates about API endpoints, build relationships with developers and establish partnerships with other API providers. Also in line with a blog, it can be the communication tool that demonstrates your supporting your API, while an out of date Twitter stream can show that nobody is home to support an API--sending the signal developers should steer clear of the platform.
  • Updates
    • 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. The change log will be another building block to keep developers updated, and reduce overall support resources needed.
    • Roadmap - API owners are asking developers to invest in building applications on their platform. This is asking for a lot of trust, and the best way an API owner can build this trust with its developers is with a transparent 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’s next. API owners need to find a balance that works for their company, and maintain an active roadmap outlining where the platform is headed.
    • Status Dashboard - API owners are asking developers to invest in building applications on their platform. This is asking for a lot of trust, and the best way an API owner can build this trust with its developers is with a transparent 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’s next. API owners need to find a balance that works for their company, and maintain an active roadmap outlining where the platform is headed.
  • Service Levels
    • Pricing - Pricing doesn’t always apply to APIs. It’s very common to provide API service for free. However, whether or not you charge for an API, you should clarify this for developers. Provide a pricing page, outlining what a developer gets for free and provide clear pricing for any other service levels, so developers will know what to expect as their usage grows. Even if the API is free, API owners should put thought into the future of the platform, set realistic expectations of how the platform will generate revenue to say in operation.
    • Rate Limits - Rate limiting is the industry standard for controlling what a developer can do with an API and reducing abuse on the platform. As with service tiers and pricing, put a considerable amount of thought into API rate limits. Make sure rate limits are in sync with service tiers, with pricing clearly posted, as well as proper relief valves so developers do not end up frustrated. Rate limits are meant to prevent abuse, not stifle innovation--put a lot of thought into the rate limits, and actively evaluate them to make sure they are achieving the objectives of the API platform.
    • Service Tiers - A well planned API will have multiple service tiers for developers to take advantage of. Before developers begin integrating their applications with an API, they need to have a clear understanding of what services are available to them. Successful API owners need to openly communicate all service tiers available, and provide simple and comprehensive descriptions of each. With no surprises on services available to them, developers can confidently build their applications on top of an API, understanding at which levels they will need to adjust their integration to take advantage of new levels of a platform.
  • Monetization
    • Advertising - Advertising is a proven monetization tool when building web or mobile advertising. Many popular APIs are deploying their own advertising platforms or integrating with existing advertising platforms for web or mobile devices. Advertising is not relevant for all APIs, but API owners should consider the opportunities advertising could offer for their API developers. There are many other monetization models being developed by API owners, and goes beyond the scope of this paper. Don’t stop with just affiliate programs and advertising, make sure and look a little deeper.
    • Affiliate Program - Affiliate programs offer business rewards to affiliates for each visitor or customer brought about by the affiliate's own marketing efforts. Affiliate programs are increasingly being integrated with API developer ecosystems, sharing API revenue with the developers that build applications around the API. Revenue sharing opportunities for developers are a great incentive for them to learn about an API, and build solid applications that consume API services.
  • Resources
    • Case Studies - APIs are all about partners and developers building new applications and finding innovative ways to integrate. When anyone builds some notable application on top of an API, develop a case study. Case studies don’t need to be novels, make them short, concise and showcase what a partner or individual developers has done. Case studies will stimulate other developers imaginations, while also showing the API is a viable platform that others are building on top of.
    • How-to Guides - Many developers can get up and running without any help at all. Other developers need a helping hand, showing them how to use the API and put code samples and SDKs to use. How-to guides can provide the essential resources for developers to get up and going with an API. Start with common integration scenarios and build how-to guides around them, then as new ways of integrations emerge create fresh how-to guides using these new ways of taking advantage of the API.
    • Webinars - Not everyone likes to read how-to guides or case studies. Many developers prefer to have a visual walk through of how to integrate with an API or the case studies of how other developers have built on top of an API. When appropriate, make webinars and videos around your how-to guides and case studies. If video productions of case studies and how-to guides are standard operating procedure, the work can occur while you produce the core paper. Youtube and Slideshare are great platforms for distributing webinars and videos of API resources.
    • White Papers - White papers demonstrate domain and industry expertise. APIs are about exposing valuable business resources and assets of a company. Producing white papers can actively demonstrate the expertise a company possess and how the API resources the company offers can solve problems and provide sounds solutions for an industry and business sector. Make white papers a regular part of the API content creation, and when ready, publish to the API area as well as syndicate across the web.
  • Research & Development
    • Ideas - As an API owner you will have ideas flowing from all directions--internally, from partners and submissions from the API community. Establishing a revolving door for ideas is important, if they don’t take hold internally and immediately get used, put them out to the community and showcase them in an idea forum. Encourage developers to submit their own, vote on, and comment or take ownership of ideas. Idea showcases stimulate developers, planting the seeds of innovation every API owner wants to see thrive in their ecosystems.
    • Labs - A labs environment for an API can be a center of innovation and inspiration for your API ecosystem. A labs environment ususally showcase experiemental and non-production projects built around your API. Labs can showcase experiemental and research development by your internal development and business staff. Encouraging internal staff members to take time and innovate around your API ccan increase their awareness of real-llife problems faced with integrating with the API. Showcasing the best of projects by your staff can also boost moral among your staff and introduce a new set of goals to achieve in their job. You may also considering exending Labs to your API development and partner community. You may need to review submissions and only showcase the best of breed. A community lab is a great way to encourage outside research & development, and build community within your API ecosystem. The are many incarnations of what an API Labs could be, spend some time and take a look at what a labs at your company may look like.
    • Opportunities - After you’ve managed developer communities for a while you will find developers are very open to suggestion and pointing them in the right direction. Some API owners are creating sections of their API communities that showcase opportunities for developers to start projects and build applications. A dedicated opportunities page, bundled with an idea showcase and a transparent roadmap will help keep developer activity in line with company goals.
  • Legal
  • Embeddable
    • Buttons - Buttons are shareable snippets of code that often share, syndicate or trigger a variety of events that benefit an API platform. Buttons play an important role in social media and social networks. Consider how Twitter’s share button has made Twitter a global communication platform or how the Digg button transformed social news. Embeddable buttons built on top of an API can significantly extend the reach of API resources.
    • Developer Badges - Badges are common for displaying content and resources delivered via an API and allow these assets to be embedded on any website or application. API platforms like LinkedIn and Google have successfully employed API driven profile badges allowing any user to take advantage of the power of an API, and grow a healthy API embeddable strategy.
    • Widgets - Widgets are highly functional, API driven JavaScript tools that provide portable applications that can be embedded on any website or application. API widgets provide tools any API user can deploy, and developers can reverse engineer, modify and extend to meet their needs. Widgets really establish an advanced API embeddable strategy and can deliver the value of an API across the Internet.
  • Environment
    • 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.
    • 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.
  • Developer Account
    • Account Settings - Along with password reset, access to their basic account detail and settings is standard operating procedure for any platform. Don’t make developers look for their settings, give quick access to settings and allow for easy updates. If developers do not have access to change their settings themselves, they will be asking you for assistance requiring additional resources.
    • Application Manager - Many popular APIs are becoming application centric and provide developers with tools for managing multiple applications or development projects. API owners should consider how developers will be building applications on top of an API and consider that many will need multiple access keys for their separate applications or user groups.
    • Billing History - Obviously if an API is entirely free, billing history is not necessary, but if any tier of API requires paid access, provide clear and easy access to what a developer has been billed, allowing them to access and download their billing history. Provide tools for developers to update their billing and account information easily, as well as support for their billing questions.
    • Developer Dashboard - Much like the landing page for the entire API platform, developers should have a single dashboard for getting at all their tools, metrics and information they need to successfully manage their usage. Developers should not have to ask, or look around for their account and access information--they should have a single place to obtain what they need.
    • Reset Password - The need to reset an account password access is pretty standard operations for any online platform. Provide the necessary tools for developers to gain access to their account if they lose their password.
    • Usage Logs & Analytics - Rate limiting will be part of any API platform, without some sort of usage log and analytics showing developers where they stand, the rate limits will cause nothing but frustration. Clearly show developers where they are at with daily, weekly or monthly API usage and provide proper relief valves allowing them to scale their usage properly.
  • Reciprocity
    • Automation - Providers like Zapier and IFTT are delivering API automation services for hundreds of popular APIs, allowing developers and end-users to further automate their operations across multiple platforms, allowing anyone to better manage their resources using very simple API driven workflows.
    • Data Portability - Providing users with the ability to get data out of a system through a bulk download and via an API is essential to reciprocity existing. Along with other basic web literacy skills that every user should possess, every person should demand that any services they sign up for, should allow for data portability of all their resources.
    • oAuth - While not a perfect standard, oAuth is the best we have when it comes to providing an identify and access layer for API driven resource, one that allows for reciprocity to occur within a single API ecosystem, and between multiple ecosystems. oAuth gives the platform, developer and end-users a (potentially) equal role in who has access to API driven resources, governing how reciprocity is realized.
    • Terms of Service - The Terms of Service (TOS) is the central hub which makes the API economy work (or not work). TOS is where the protections for platform owners, developers and end-users exists. Restrictive TOS can suffocate the reciprocity of platform, while more sensible ones allow for the movement, and collaboration around resources that will make a platform thrive.


DIY API Management

Tackling API management on your own is a realistic strategy. There are many companies and even individuals who manage one or many APIs by designing and deploying their own interfaces and cobbling together a management platform using common cloud services and open sources tools.

While a robust, API portal, complete with service composition, billing, analytics and other tools is optimal, a DIY approach is a cost effective approach that can get you to proof of concept and production without added costs of software and contracts.

It can be very difficult to anticipate what will happen in the deployment and operations of an API. While you can establish a base strategy for your API, most iniatives are real-time research and development around business data and resources, something a DIY approach is well suited for.

API service providers tend to focus on delivering tools for you to secure, manage developers, analytics and billing solutions. These are all very valuable tools for any API provider, so make sure and consider using one of the providers alongside a DIY approach. It is not necessarily a DIY vs. API management service provider question.

There are numerous tools and services that can be used to augment your API management. This paper focus on a handful that are used by existing API providers and augment proven approaches to API management very nicely.





Poor API documentation is the number of pain point for developers. Out of date, poorly written documentation can make API on-boarding a nightmare.  There are several building blocks that can help you deliver in the area of documentation.

Carte - https://github.com/devo-ps/carte

Carte is a simple Jekyll based documentation website for APIs. It is designed as a boilerplate to build your own documentation and is heavily inspired from Swagger and I/O docs. Fork it, add specifications for your APIs calls and customize the theme. Go ahead, see if we care.

Flask API - http://flaskapi.org/

Flask API is an implementation of the same web browsable APIs that Django REST framework provides. It gives you properly content negotiated responses and smart request parsing.

I/O Docs - https://github.com/mashery/iodocs

I/O Docs is a live interactive documentation system for RESTful web APIs. By defining APIs at the resource, method and parameter levels in a JSON schema, I/O Docs will generate a JavaScript client interface. API calls can be executed from this interface, which are then proxied through the I/O Docs server with payload data cleanly formatted (pretty-printed if JSON or XML).

Swagger UI - http://swagger.wordnik.com/

Swagger UI is part of Swagger project. The Swagger project allows you to produce, visualize and consume your OWN RESTful services. No proxy or 3rd party services required. Do it your own way. Swagger UI is a dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation and sandbox from a Swagger-compliant API. Because Swagger UI has no dependencies, you can host it in any server environment, or on your local machine.



The goal of any API provider to help consumers go from signup to successful integration as fast as possible. Providing code in as many possible languages, frameworks and formats is the best way any API provider can help their community.

Github - http://github.com

GitHub is a web-based hosting service for software development projects that use the Git revision control system. GitHub offers both paid plans for private repositories, and free accounts for open source projects.

Github Gist - https://gist.github.com/

Gists are snippets of code. They can be entire applications, or they can just involve a single file. Best of all, every gist is a git repository, which means that they can be forked, cloned, and manipulated in every way.



A well written, active blog with an RSS feed can become the face of an API. Providing much needed stories and resources about API integration, but also providing rich SEO content that will act as a discovery engine on the open web for an API. In contrast an inactive blog can quickly begin to wrok against you, so make sure if you consider blogging as part of your API management strategy it plays and active role.

Blogger - http://blogger.com/

Blogger is a blog publishing platform formerly known as Pyra Labs before Google acquired it in February 2003. Blogger blogs are mostly hosted internally with the “dot Blogspot” domain but they can also be hosted externally on a user’s own server.

Jekyll - http://jekyllrb.com/docs/home/

Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through Markdown (or Textile) and Liquid converters, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server. Jekyll also happens to be the engine behind GitHub Pages, which means you can use Jekyll to host your project’s page, blog, or website from GitHub’s servers for free.


Tumblr - http://tumblr.com

Tumblr, stylized in their logo as tumblr., is a microblogging platform and social networking website, owned and operated by Tumblr, Inc. The service allows users to post multimedia and other content to a short-form blog. Users can follow other users' blogs, as well as make their blogs private. Much of the website's features are accessed from the "dashboard" interface, where the option to post content and posts of followed blogs appear.

Wordpress - http://wordpress.org/

WordPress is an open source blog tool and publishing platform powered by PHP and MySQL. It's often customized into a Content Management System (CMS). It has many features including a plug-in architecture and a template system. WordPress is used by over 14% of Alexa Internet's "top 1 million" websites and is widely regard as the most popular CMS on the internet according.



User groups and forums have become an essential building block in API communities for self-service support. A well moderated, active forum can evolve an APIs development area into an actual community. All forum communities will require the API owner to engage developers, keeping conversations active and questions answered, but with the right developers your forum can become self regulating--with opportunities for community participation.

Get Satisfaction - http://getsatisfaction.com

Get Satisfaction is the community platform that helps companies create engaging customer experiences by fostering online conversations about their products and services at every stage of the lifecycle. Get Satisfaction powers 70,000 active customer communities hosting more than 35 million consumers each month. From its inception in 2007, Get Satisfaction has been focused on building an intuitive, easy to use community platform that is designed to bring resolution to consumers; is highly discoverable by search engines and is implemented quickly and easily.

Google Groups - http://groups.google.com/‎

Google Groups is a free service from Google Inc. that supports discussion groups, including many Usenet newsgroups, based on common interests.Membership in Google Groups is free of charge and many groups are anonymous. Users can find discussion groups related to their interests and participate in threaded conversations, either through a web interface or by e-mail. 

UserVoice - https://uservoice.com/

UserVoice creates simple customer engagement tools that help companies understand and interact with their customers more positively and build customer relationships that last. UserVoice Feedback - a hosted tool for gathering and prioritizing product ideas directly from a company’s customers. UserVoice Helpdesk - a simple-to-use ticketing system that helps companies solve more customer issues in less time. UserVoice Full Service - a complete customer service solution that bundles Feedback and Helpdesk into a single, easy-to-manage environment.


Providing direct and indirect support for an API community will support new and active developers, while also stimulating word of mouth marketing around an API ecosystem. Support should be kept public as often as you can, but provide ticketing, email and other private support channels as well.

Zendesk - http://zendesk.com

Zendesk provides an integrated on-demand helpdesk - customer support portal solution based on the latest Web 2.0 technologies and design philosophies. The product has an elegant, minimalist design implemented in Ruby on Rails and provides seamless integration of the back-end helpdesk SaaS to a company’s online customer-facing web presence, including hosted support email-ticket integration, online forums, RSS and widgets.   This is unusual, because most SaaS helpdesk solutions focus exclusively on the backend helpdesk and treat the Web as an afterthought.  



Providing a status dashboard for an API is critical in building trust and goodwill within an API community. Beyond providing communication and much needed awarenes amongst users, a status dashboard provides a very public bar for API operations, stability and reliablity. Something that can go a long way in setting an API apart from the growing number of API driven resources.

Stashboard - http://stashboard.org/

Stashboard is a status dashboard for APIs and software services. It's similar to the Amazon AWS Status Page or the Google Apps Status Page. Stashboard was originally written by Twilio to provide status information on its Voice and SMS APIs. Stashboard is designed to provide a generic status dashboard for any hosted service or API. The code can be downloaded, customized, and run anywhere.



APIs are active, real-time research and development departments, so measuring everything is essential. Analytics at all layers of operations is critical for API providers to understand how resources are being used, and delivers insight into how they can be made better. Analytics also provide API consumers with quality data on how they are using resources, and opportunities for making applications and usage more efficient.

Graphite - http://graphite.wikidot.com/

Graphite is a highly scalable real-time graphing system. As a user, you write an application that collects numeric time-series data that you are interested in graphing, and send it to Graphite's processing backend, carbon, which stores the data in Graphite's specialized database. The data can then be visualized through graphite's web interfaces.

Stats D - https://github.com/etsy/statsd

StatsD is a dead simple NodeJS daemon that listens for messages over a UDP port. When a message is received, it parses the messages, and extracts metrics data. StatsD lets you define what you want to track, throw it at the StatsD over a UDP port, once processed you can schedule it to dump to Graphite for further processing and visualization.


API Management Providers

Web API management as a service has been going on for over six years now, and combined with the wealth of SOA experience amongst the providers you can be pretty sure that the companies who have been in the business for a while, know what they are doing.  

The first wave of API experience comes out of the enterprise, but quickly a new breed of web API focused companies emerge who redefined the way you manage APis, with an emphasis on open and public.  

In 2014, there are over 20 API management providers ranging from the classic enterprise focus, to data to API solutions in the cloud. While there are differences between these providers, they all have a great deal of experience in planning and execution of API management for a wide variety of API resources.



3Scale provides plug-and-play as well as enterprise level API management services. 3Scale is similar to 3Scale connect is a starter platform with a freemium model for delivering your API. You can deploy at no cost, and pay-as-you-go based upon the volume of calls made on your API. This model is well suited to those who are not sure of their API business model or target audience — or are just looking to test the waters.


API Metrics

APImetrics builds on 3 years experience gained working on the challenge of API abstraction and management that is critical to every App and Web Service in use today.  By combining elements gained from API management tools and authentication technologies, APImetrics have been able to build the first, complete, end-to-end API performance test solution.  This allows developers, enterprises and API providers to model complex API scenarios and provide them with real time monitoring and alerts when things go wrong.



ApiAxle is a proxy that sits on your network, in front of your API(s) and manages things that you shouldn't have to, like rate limiting, authentication and caching. It's fast, open and easy to configure.  ApiAxle is different to the cloud based services such as Mashery in that it’s intended to be installed within your LAN and be managed by you. This means you own your users, you own your data and you can more easily manage costs. ApiAxle is open-source. This means you can modify it as much as you like and contribute changes back. Others will do the same and gradually the system will become all the better for it.



Apify is a small and powerful open source library that delivers new levels of developer productivity by simplifying the creation of RESTful architectures. It helps development teams deliver quality web services and applications in reduced amounts of time.  Web services are a great way to extend your application, however, adding a web API to an existing web application can be a tedious and time-consuming task. Apify takes certain common patterns found in most web services and abstract them so that you can quickly write web APIs without having to write too much code.



Apigee is a provider of API technology and services for enterprises and developers. Providing a range of solutions from entry level tools for exploring APIs with a console and navigating OAuth, to enterprise tools for managing OAuth, Keys and platform for driving developer adoption while understanding usage, managing traffic and scaling an API platform.  Apigee provides solutions for enterprises like Comcast, GameSpy, TransUnion Interactive, Guardian Life and Constant Contact and thousands of developers use Apigee's technology.

Apigee provides resources to help you understand best practices, avoid common pitfalls, develop your strategy, and learn to drive your developer community. Apigee also provides articles, white papers, and other resources to help you deliver your API.




APISpark is an  cloud API platform that lets you create, host, manage and use web APIs. Using the Restlet Framework at its core, APISpark simplifies the web API experience, the time to market, and the overall cost to get started and to scale you APIs.  Restlet is a web API platform vendor, pioneer of RESTful web APIs.  APISpark serves our customers around the world, providing software to build web APIs, which includes APISpark, the PaaS version of Restlet.  APISpark lets you build and deploy your web APIs, which includes the creation, hosting and management--all in one solution.



Simple and frictionless access for developers is key to the success of any API program. Minimizing the time it takes for a new developer to complete a transaction with your API is crucial. API Management generates great documentation and provides an interactive console that rapidly increases developer success.



Exicon is the AppCycle management company that simplifies the creation, deployment and management of mobile applications for some of the world's biggest companies allowing them to accelerate their success in mobile.

Through its proprietary AppCycle Management platform, Exicon provides the services and tools to support customers in defining their application needs, finding the best developers, storing all components of the applications, reaching the end users for your application and measuring its performance.



The product that ops provides to developers. Ops should be a product team, not consultants. Flynn is the single platform that ops can provide to developers to power production, testing, and development, freeing developers to focus.



IBM® API Management solution provides a complete set of web API capabilities to help you extend services from the back-office to new front-office engagements. It offers flexible deployment options, including capabilities for creating, proxying, assembling, securing, and scaling web APIs. IBM API Management provides detailed analytics and operational metrics to the business owner, as well as a customized developer portal for socializing the APIs and managing applications that can be used by developers.


Layer 7 Technologies

Layer 7 is a leading provider of API security and governance for Service Oriented, Web Oriented and Cloud Oriented integration.  Through our award winning line of SecureSpan and CloudSpan family of API gateways and management products, Layer 7 is helping organizations control how they expose their data and applications to outside divisions, partners, mobile developers and cloud services.

Founded in 2003, Layer 7 operates in the US, Canada and Europe. Our customers include leading insurance, banking, telecom and government organizations. The company is venture backed by leading Canadian and US investors.



Mashape provides tools that enable developers to quickly deliver and consume APIs and offers a marketplace for listing APIs.  Mashape provides tools for testing your API, code for generation of custom errors, components for user management and standardized API code language libraries in multiple languages.  Once your API is ready for prime time Mashape provides a marketplace for listing your API, letting developers to easily discover and begin hacking with your API, in a social API community environment.



Mashery’s API management tools and strategic services help companies connect with customers and partners in a changing digital world by extending reach across devices, markets and the Web. Mashery leads the industry with a holistic approach for API initiatives – from setting platform strategy and measuring business objectives to the heavy lifting of providing and managing infrastructure to facilitating relationships with our 150,000 strong network of Web and mobile application developers. Having worked with over 100 leading brands to power more than 40,000 apps, Mashery’s knowledge, experience and proven strategies enable companies to focus on their core business while driving sales, building new revenue channels and realizing faster time-to-market for innovative applications.



MuleSoft provides the most widely used integration platform for connecting SaaS and enterprise applications in the cloud and on-premise. With the rise of cloud and mobile, enterprises face a choice: get overwhelmed by the resulting explosion of end points or seize the opportunity to gain competitive advantage. Founded on the idea that connecting applications should not be hard, MuleSoft lets organizations harness the power of their applications through integration. MuleSoft’s Anypoint™ technology eliminates costly, time-intensive point-to-point integration, enabling business agility. Delivered as a packaged integration experience, CloudHub™ and Mule ESB™ (Enterprise Service Bus) are built on proven open source technology for the fastest, most reliable on-premise and cloud integration without vendor lock-in.


Nevatech Sentinet

Nevatech Sentinet™ is a flexible, lightweight and scalable API management platform that promotes integration through the use of SOA standards. It is designed to connect, mediate, and manage interactions between services across the enterprise or in the cloud. If your organization uses internally or externally-facing web services and APIs, cloud-based infrastructure, or service-oriented architecture for your applications, then you will find Sentinet to be a powerful tool, which can be deployed rapidly, and immediately start delivering tangible results.



Secures service-oriented architecture (SOA) deployments on-premise, across domain boundaries, or in the cloud enabling organizations to securely and rapidly adopt cloud, mobile, and SOA services. Provides a lightweight API gateway for securing and managing APIs. Connects mobile devices to existing enterprise systems. Significantly lowers integration costs, decreases total cost of ownership, and reduces deployment risks. Offers rich integration with many identity and access management platforms. Helps streamline regulatory compliance through authentication, authorization, and audit capabilities.



SlashDB connects your internal databases and constructs a REST/HTTP web service, easily making database content accessible by URLs for getting, updating, inserting and deleting in a secure way.  SlashDB provides connectors for Microsoft SQL Server, Oracle, MySQL, PostGreSQL, IBM DB2 and Sybase--covering the top 5 databases you will find in the enterprise or small to medium businesses.

SlashDB automatically turns databases into online resource so their content becomes accessible to authorized web, mobile and enterprise applications for reading and writing under standard data formats. Technically speaking, it makes REST APIs out of relational databases.


SOA Software

SOA Software, Inc. provides API management and integrated service-oriented architecture (SOA) governance automation solutions. It offers Enterprise API Management; Policy Manager, which provides SOA registry/repository and SOA policy governance solutions; Repository Manager, which provides software development asset repository, lifecycle management, and metadata federation solutions; and Portfolio Manager, a planning governance product that helps ensure the alignment of SOA programs with strategic IT investment and business objectives. The company also provides Service Manager, a SOA management and security product, which provides security, routing, mediation, monitoring, and management for SOA and Web services; and SOLA, which provides a governable mainframe SOA platform.



StrikeIron is the leader in Data-as-a-Service (DaaS), delivering data quality and communications solutions via our cloud platform IronCloud. We provide address verification, email verification, phone validation, phone append, SMS text messaging, and sales tax solutions to customers in a variety of markets. Our solutions are delivered as Web services that can be easily integrated into any application or system. Additionally, our solutions are pre-integrated into leading platforms like: Salesforce.com, Magento, Informatica, Oracle CRM On-Demand, and more. 



StrongLoop is based in San Mateo, CA and employs over 30 developers working with Node.js. StrongLoop develops StrongLoop Suite, a leading Mobile API Tier along with being the primary code contributor to Node.js. StrongLoop Suite includes an open source private mBaaS, an operations console and a supported package of Node.js, containing advanced debugging, clustering and support for private npm registries. StrongLoop was founded by Node core-contributors, Enterprise mobile architects and veterans of open source and Could companies. StrongLoop is backed by Ignition Partners and Shasta Ventures and includes Marten Mickos, CEO of Eucalyptus (previously MySQL) as an advisor.



SwiftIQ provides web-service application programming interface (API) infrastructure to facilitate data accessibility and predictive analytics through the Swift Access and Swift Predictions products. Swift Access is an award-winning backend platform to unify and secure disconnected data then deliver and analyze it on-demand to power real-time digital actions. Swift Predictions allows users to apply adaptive, machine learning algorithms to discover insights fast and make applications smarter. The Company was founded in 2011 and headquartered in Chicago, IL.



Vordel API Gateway is a policy enforcement point to authenticate API clients and users against enterprise access management platforms. Vordel adds advanced capabilities such as security token mediation for single sign-on and identity federation. Vordel API Gateway also integrates with fine-grained authorization tools to externalize authorization for new and legacy applications. Vordel offers out-of-the-box integration with all the leading identity management platforms to provide comprehensive API Security.



WSO2 is the lean enterprise middleware company. It delivers the only complete open source enterprise SOA middleware stack purpose-built as an integrated platform to support today’s heterogeneous enterprise environments internally and in the cloud. WSO2’s service and support team is led by technical experts who have proven success in deploying enterprise SOAs and contribute to the technology standards that enable them.


No Matter Which Path You Choose

With API management, it comes down to whether or not you have the skills and resources to tackle managing your entire operations without the assistance of an API management service provider.

If you are part of a larger enterprise entity, you will most likely have options available to you through your existing IT Operations. But there is still a lot you can learn from the approaches by public API providers, and how they handle their API management.

For most companies, just learning about the API space, budgets will be tight, and you will have to cobble together what you need to get to a proof of concept. While just learning, experimenting and iterating, with an API, it can be tough to enter into contractual obligations for API management services. While you have to be mindful of costs while learning, the API management service providers can bring a wealth of experience to the table and potentially prevent serioius mistakes and possibly save you time and money.

No matter which path you choose, the DIY, or service provider, or a hybrid of both, it is highly recommended you maintain full control over API management across all parts of a business. API management is not just an IT or developer initiative. APIs are something that business and marketing departments need to be deeplky involved with from design to management operations.



Appendix A: Curated News and Resources