Developer Community Management
API Management is about much more than just monitoring an API.
It is about making sure you build the right API with API Planning; build them correctly using an API Development solution; make sure they are behaving correctly with API Operations infrastructure; and supporting all of this with a common underlying set of API Management services.
Of course, at the end of all this all you have is a service published outside your enterprise. It’s really not an API yet, not until you publish, promote it, and support it through your developer community. One of biggest problems you face is that you really don’t know how to tell people about it, and when you do find someone who’s interested, you have to be able to feed them all the information they need to use it without getting overwhelmed trying to support them all.
This is where the Enterprise API Platform (EAP) shines, regardless of whether you are trying to broadcast your Open API to the whole wide world, or to expose an Enterprise API to groups of developers inside your own business. EAP allows you to market your API or App inside or outside your enterprise with a powerful search driven catalog offering rich social features like ratings, reviews and following. You can publish your API into EAP with appropriate descriptions and tags to make it easy for potential consumers to find it through search and browse, including external (public or enterprise) search engine integration and optimization.
Of course, once someone has found your API, they need to decide if it is the right API for them to use. This is where the definition and documentation capabilities come into play, and where the discussion forums and user following capabilities allow them to ask questions, or see how active the community around your API is.
People need to be able to use your API without burdening you with a ton of questions and complaints. You need to ensure that you define it properly, document it well, and publish the definition and documentation effectively.
EAP provides a robust set of tools for API definition, documentation, and content management, as well as policy and lifecycle management. This allows you to make sure your APIs are correctly structured and well documented. EAP also integrates well with internal design and development processes to help make sure that the internal services and applications that support your API are up to the task.
API Search Index
Good stuff, you’ve defined your API properly and have published it with well-structured documentation. It’s in the catalog with a nice description, an appropriate name and set of icons, and you’ve even convinced a few friends to post nice encouraging reviews and ratings for it. Now it’s time to hope that potential users can find it.
EAP provides a very powerful built-in system that creates an internal search index from all the content about the APIs and Apps that it is aware of, complete with sufficient permission information so that it knows which users it can show search results for particular APIs and Apps to. Hopefully the phrase “all the content” caught your eye, because that’s one of the more interesting things here. The content about your API or App doesn’t just include its name and any description information you typed in, it also includes all the documentation, and most importantly all the discussion topics and comments posted about it. This means that if someone asks a question on your API’s Board about how it handles a particular type of widget, then when someone searches for anything to do with that widget, they will find your API. Think about the use-case where you are writing a piece of code and you run into a problem and use Google to search for the specific error code or exception text. Because EAP is indexing all this information, these types of searches work in real-time.
Maybe even more important in EAP’s search capabilities is its ability to publish and maintain its index in enterprise or public search engines. This means that your developers can find information about your API regardless of how they look for it.
App Connection Provisioning
You’re making real progress with your API now. It’s well defined and documented, you’ve published it into a dynamic catalog where users are able to find it, rate it, review it and discuss it. What more could you possibly want?
How about allowing Apps to actually use your API, and controlling the way they use it? EAP allows developers to define their Apps – in much the same way that you defined your API. In fact, the App definition has all the same features with documentation, ratings, reviews, discussion boards and the whole nine yards, as your API definition. It also allows the developer to create a team of peers that can work together on the App. This may all seem a bit fluffy and useless, until we get to the real purpose of the App definition.
EAP provisions API access individually to each App. It creates an identifier for the App, and the App developer can upload a CSR (certificate signing request) for a locally generated public key. The App will then use this App-id (optionally signed) to authenticate itself to EAP. The App developer will find the API(s) they want their App to use, and will initiate a simple approval workflow to grant their App access to the APIs. Depending on how the API is configured, they can also request different throughput levels based on pre-defined quota policies. Once the workflow process completes and their App’s access to the API(s) is approved, the App can begin sending requests to the API.
There’s quite a bit more to this, including the ability for an API to expose sandbox (test) and production endpoints, with a multi-step approval process for granting Apps access to each of the endpoints. This may sound complex, but in most circumstances, sandbox access will be automatically approved, and getting approval for production access is a simple process involving a single button click for the App developer, and a simple response to a newsfeed item and/or notification from the API administrator.
One of the interesting side-effects of this provisioning process is that Atmosphere is able to monitor the API from the perspective of each of the Apps. The API administrator can see all of the monitoring data and can choose to see a pie chart showing which Apps are consuming their API the most, they can filter the monitoring data by App to provide support for a particular App owner, or can use this data to identify poorly written or malicious Apps that are causing problems for their API, so they can disable or throttle them appropriately. Similarly, the App owner will see the API from the perspective of their App only. They will only see their traffic and performance information, and the usage data and messages their App is generating.
Assuming you’re following along with the various steps above, then by this point you now have a rock solid API that is well structured and documented, published in a catalog with great search facilities, and is protected from all kinds of bad things. Developers are starting to find it through the traditional search and browse models, but that’s not good enough in today’s social-media driven world. You need your API (or App) to go viral. Bring on the social world.
EAP is the social platform for API Management and App development. It brings together API providers and App developers in an online social community. Whether this community exists inside your enterprise, as a private external community, or part of a broad public developer community is entirely up to you. EAP’s social features include:
Any EAP user, developer, business administrator, or API provider can invite other users to the party. Invitations can be general, simply inviting a user to check out the specific EAP instance, or they can invite a user to follow an API, App, or Group, or join the development team for an App. In this way you can immediately create your own communities of interest around your APIs and Apps. By encouraging the people you invite to invite their contacts too, you can build a huge social community connected to your resources.
One of the bigger challenges you’ll face with your API is the potential of becoming a victim of your own success. What’s going to happen when you drive this massive social adoption of your API? How on earth are you going to manage the volume of support requests and questions you’re sure to get?
Again, EAP has the answers. The first thing, of course, is to make sure that your API is well structured and well documented, as we discussed earlier. You can make developers’ lives even easier by providing them with SDKs and code samples, and EAP allows you to publish and promote these with your API. But where the real beauty kicks in is when your developer community becomes self-sufficient and users start helping each other out by answering questions and even responding to trouble tickets. Because everything is so efficiently indexed, it’s really easy for users to search for errors, issues or questions, and get immediate help and answers from questions and issues that have already been resolved. Sure, you’ll have to put some effort into getting your community moving, but the time and energy you dedicate early on will pay enormous dividends later. As my mother used to say, “A stitch in time saves nine.”
B2B API Integration
Of course not every API will be destined to be truly “Open” - designed to target a broad community of App developers sharing ideas and applications in an open forum. In fact, we expect to see far more private or semi-private APIs that a business uses to share specific functions or data with one (private) or more (semi-private) partners.
EAP enables this by introducing the concepts of API and App privacy settings, enabling a number of key scenarios:
In one of the most common scenarios you may have an API that you wish to use to enable integration with several partners, but you don’t want any of the partners to know anything about each other, or even to know that there are other partners using the API. EAP allows you to define a private API and invite users to follow and connect to it – the invitations are required, because the API will not be published in the search indexes and will not be visible to any user who has not been specifically invited. In this mode, user posts, discussions and comments will be visible only to that user and to the API administrators.
Another common requirement for private APIs is the need to create an API that is visible and consumable by a defined (invited) group of users. Any member of the group will be able to see posts and comments from other members, but the API and all its content will be hidden from anyone outside that group. This is particularly useful as a tool for publishing a version of an API for use by a beta test group, in advance of launching the API to the public.
Share Developer Communities
All these capabilities sound great, but at the end of the day, the success of your API initiative depends very much on your ability to get your API in the hands of as many developers as possible. So how can you go about building your own developer community? Maybe a better question would be, why should you go about building your own developer community when there are already a bunch of communities out there? More to the point, what about your partners or other like-minded companies with their own APIs that a developer building an App that uses your API might also use?
EAP supports the concept of API provider federation to bring together communities giving developers access (with approval) to any API from any provider using a single App ID, and allowing providers to leverage the network effect of all the connected communities to find the broadest possible reach for their API. All this is done with federated trust and permission models that allow API providers to opt in or out at granular levels, and to choose the partners with whom they want to federate.
Because we offer EAP as a PaaS platform as well as via on-premise or hybrid models, there will be a ready-made community for EAP customers to connect to, whether they choose to create their own tenant in the EAPaaS platform, or install the product in their own datacenters. Customers will be able to choose how much or little sharing they do with the broader community, depending largely on how ‘Open’ they view their APIs.