API Developer Community
May 12, 2020

How to Build an API Developer Community

Developer Portal

Building an API community and developer community will democratize your digital offerings and provide a new competitive advantage for your organization.

But what is an API community?

Your API community are the people who consume your available APIs, which are most often found via your developer portal. In short, your API community are all the people who benefit from using your APIs within and outside your organization. 

What is a developer community? 

Your developer community are the developers who consume, repurpose, and innovate using your available APIs. This developer community can include developers within your organization and outside your organization. A key aspect to growing your external APIs is evangelizing them among a relevant developer audience. 

API Community: Why It Matters

Enterprises that make business applications available through APIs drive business growth and expose new digital opportunities. The business landscape is being reshaped, reflecting an environment similar to the late 1990s. The rush to create websites in the 90s has been supplanted with the rush to create APIs in modern times. APIs have become the primary means that businesses interact with their customers, reach new markets, and enable app developers to innovate with an organization's digital offerings.

You can think of APIs like products. Likewise, it is important to identify the right business capabilities to expose as APIs, using this product mindset. When your APIs are well designed, well supported, and promoted effectively, the result will be a flourishing developer community.

This blog post will discuss the key steps for ensuring your APIs are optimized for growing an API and developer community.

A Developer Community Starts With Sound APIs

Whether you’re just getting started with APIs, or already have APIs in production, you need a solution that makes this process simpler. This allows you to focus on the business value and functionality of your APIs. In other words, if your APIs have nothing to do with your core business functionality, leave the heavy lifting to an enterprise API platform.

Building the Right APIs

APIs don’t exist in little self-contained packages installed in your enterprise DMZ. In most cases, APIs will be externally-facing interfaces of one or more internal applications, often using existing enterprise services.

The big challenge is taking an existing service interface that is often implemented using SOAP with WS-Security, or plain old XML (POX) over JMS or MQ, and turn it into a RESTful API with XML and/or JSON content. It is especially important with mobile applications to deliver the least amount of data possible to get the job done, with the least amount of back and forth dialog.

With the right enterprise API platform, you can quickly and easily create properly defined and structured RESTful APIs supporting XML and JSON. These can be built on top of existing internal services. Your API management solution should mediate between content types, transport protocols, security models, message exchange patterns, standards, and more. This will allow you to get your API up and running quickly.

An API Is Not an Island

Even though you may think of your APIs as entirely new products, they still rely on existing applications. In an enterprise context, they should be integrated with your enterprise security and management systems, and with existing enterprise services and applications.

A solid enterprise API platform will come with out-of-the box mechanisms for integrating with your enterprise identity and access management systems. This allows your developers to login to the community using enterprise-controlled credentials, while APIs and apps can work with existing managed user accounts. This allows for using single sign-on between apps and enterprise applications. This ensures your app developers and end users remain subject to existing security and privacy requirements.

The enterprise API platform will also be able to integrate with enterprise management and monitoring products. This way your enterprise network operations center can manage performance and availability, and can leverage your existing investments in enterprise database infrastructure and datacenter operations.

Building APIs for an API Community

It’s tempting to think of an API deployment as a skunkworks project designed to get something off the ground fast. Yes, you want to be fast to market with APIs, but you’d better get it right. Especially if your community will make use of your APIs.

Your enterprise API platform should help you optimize your investments with strategic planning to ensure you build the right APIs at the right time, meeting current and planned needs, understanding the dependencies between the API and existing business processes and applications. This means clean API definitions, good documentation, and the right amount of architecture and program management support.

Once you’ve built your APIs, your enterprise API platform should provide the runtime infrastructure to ensure they are behaving. Meeting QoS and security requirements is critical. Finally, your enterprise API platform should help you with the process of publishing, socializing, and supporting your API. This will ensure your API community thrives.

Evangelizing APIs

So you’ve built the best API in the history of APIs. Tons of businesses will use it and thousands of apps with millions of users will keep pouring in. The only problem is you don’t know how to tell people about it. When you do find someone who’s interested, they need all the right information without getting overwhelmed. Only then can they can leverage your APIs.

This is where your API developer portal comes into play. You need a social enterprise API platform, regardless of whether you are trying to broadcast your open APIs to the whole world or expose them to a small group of developers inside your own business.

You want to market your APIs and apps inside and outside your enterprise. This requires a powerful search-driven catalog offering rich social features like ratings, reviews and ‘following'. You need to publish your APIs into a catalog with appropriate descriptions and tags to make it easy for potential consumers to find them. This requires search and browse features, including external (public or enterprise) search engine integration and optimization.

Of course, once someone has found your APIs, they need to decide if they are relevant. This is where 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 your API community is.

Related >>  What Is an API Portal?

Defining and Documenting Your APIs

People should be able to use your APIs without a ton of questions and complaints. You need to define, document, and publish the definition and documentation effectively.

A good enterprise API platform will provide a robust set of tools for API definition, documentation, and content management, as well as policy and lifecycle management. This ensures your APIs are correctly structured and well documented. The solution should also integrate with internal design and development processes. This confirms that your internal services and applications supporting your APIs are up to the task.

Ensuring the Developer Community Can Find Your APIs

You’ve defined your APIs and published them with proper documentation. Thy are in the catalog with a thorough description, an appropriate name and icons, and you’ve even convinced a few friends to post encouraging reviews. Now it’s time to hope that potential users can find them.

Your enterprise API platform should offer a ready-build internal search index for APIs. This should include all content about APIs and available apps, complete with permission thresholds to show select users relevant and available APIs and applications.

Hopefully the phrase, “all the content” caught your eye, because that’s one of the more interesting things here. The content surrounding APIs or apps doesn’t just include its name and description. This also includes documentation, and most importantly all discussion topics and comments posted. This means that if someone posts a question on your API’s community thread about how it handles a particular type of widget, searchers looking for widget content can find these conversations and related APIs. 

Consider writing a piece of code, running into a problem, and using Google to search for a specific error code or exception text. Full-service enterprise API management platforms will index this information, so these searches can work in real-time.

Another important consideration for your search system is its ability to publish and maintain an index across enterprise and public search engines. This will allow your developers to find information about your APIs regardless of where they search.

Managing Connections Between Apps and APIs

You’re making real progress with your APIs now. It’s well defined and documented, you’ve published it in a dynamic catalog where users are able to find, rate, and review. What more could you want?

How about allowing apps to actually use your API. And controlling the way they use it. API management allows developers to define their apps – in the same way you defined your APIs. 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 allows the developer to create a team of peers that can work together on an app. This may seem a bit fluffy and useless, until we get to the real purpose of the app definition.

App Definitions: The Value to APIs

Your enterprise API platform should provision APIs' access individually to each app. It should create an identifier for the app, allowing the app developer to upload a CSR (certificate signing request) for a locally-generated public key. The app should then use this app ID (optionally signed) to authenticate itself to the API management solution. The app developer should use the enterprise API platform’s developer community to find the APIs they want their app to use. In addition, they can initiate a simple approval workflow to grant their app access to the APIs.

Depending on how the APIs are configured, they could also request different throughput levels based on pre-defined quota policies. Once the workflow process completes and their app’s access to the APIs is approved, the app will be able to begin sending requests to the APIs.

And that’s not all. Your APIs should be exposed to 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. Getting approval for production access is a simple process for the app developer and a simple response to a newsfeed item, or notification from the API administrator.

An interesting side effect of this provisioning process is your enterprise API platform can monitor the APIs from the perspective of each app. The API administrator can see all monitoring data and view which apps are consuming their APIs most readily. They should be able to filter the monitoring data by app to provide support for a particular app owner. Or, use this data to identify poorly-written or malicious apps causing problems for their APIs. Then, they could choose to disable or throttle them appropriately. Similarly, the app owner can see the API from the perspective of their app only. They would only see their traffic and performance information, as well as the usage data and messages their app generates.

Protecting Your API

When it comes to API security, there are a couple of things you have to be wary of:

  • First off, do your APIs expose sensitive information or even enable business transactions? For example, it would be a really bad idea to overlook security when you deliver an API that exposes private information about your customers, or allows people to move money from one account to another. Consider implementing FAPI (Financial-grade API) protocols in these scenarios. 
  • Regardless of whether your APIs needs sophisticated security or not, it will still be vulnerable to abuse, intentional or otherwise. You need to control the amount of traffic each application is able to send to your APIs to ensure that one app can’t dominate the APIs, preventing other apps from using it; and to protect your internal systems from the damage that could result from the APIs overloading them with traffic.

API Security Protocols

A good enterprise API platform will provide a rich array of security capabilities for all types of APIs. This will include the ability to mediate between security models, standards, and technologies to ensure seamless interoperability between externally-facing APIs and the internal services that support them. These security capabilities should include:

  • Authentication: At a minimum, the enterprise API platform must be able to authenticate the apps that are consuming your APIs. It should support a wide array of token types from simple http headers (unsigned or signed), through x.509 certificates and highly advanced WS-Security headers.
  • Token Exchange: The enterprise API platform should take the credentials provided by the app and use them to generate a whole new token as needed by your internal APIs. For example, it could authenticate an app using a signed http header, and generate a signed WS-Security SOAP transport, or a SAML assertion for use by your internal service.
  • Cryptography: The enterprise API platform should provide a built-in PKI system and Certificate Authority for generating and distributing public/private key pairs and certificates. It should provide policies for specifying a wide range of different types of message signature and encryption supporting all common standards.
  • Federation: The enterprise API platform should allow an app to use a single credential to consume many APIs, even if the APIs are offered by different companies with their own API Management platforms. For more on this see the section below on API provider federation.

All these capabilities, and the huge range of supported standards and configuration options, could make for a very complicated product. But a well-designed enterprise API platform keeps things as simple as possible, providing canned configurations for common scenarios with a comprehensive set of wizards for more advanced use cases.

Read More >> API Security Best Practices

Quota Policy

An enterprise API platform should provide a powerful quota policy system allowing API administrators to provision capacity to apps as needed. This means that an administrator who knows how much traffic the API can handle could apportion this capacity over the apps that are consuming the API appropriately. For example, if an API can handle no more than 200 transactions per second (tps) the administrator may choose to allow an important customer-facing application to consume 100tps, and could then allow 5 less important apps to consume only 10tps each. The remaining 50 apps would be only allocated 1tps. This is obviously just one way to apportion capacity. 

The enterprise API platform should allow app developers to negotiate the quota allocated to their app during the access provisioning process, and facilitate a dialogue between the app developer and the API administrator if the app needs more or less capacity at any point in the future. It should enforce the quota policies at runtime, denying or queuing up any requests that exceed an app’s allotment.

Socialize Your API

Assuming you’re following along with the various steps above, then by this point you now have  rock solid APIs that are well structured and documented, published in a catalog with great search facilities, and protected from malicious intruders. Developers are starting to find your APIs through traditional search and browse models. But that’s not good enough in today’s social-media driven world. You need your APIs (or apps) to go viral. Bring on the social world.

An enterprise API platform will provide the social platform for API management and app development. It will bring 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. The enterprise API platform’s social features should include:

Invitations

Any user, developer, business administrator, or API provider should be able to invite other users to the party. Invitations should be general, inviting a user to check out the community, or to follow an API, app, or group. This allows you to create your own communities of interest around your APIs and apps. By encouraging the people to invite their contacts, you can build a relevant social community connected to your resources.

Social Forums

Every API, app, user, business or group inside your enterprise API platform should have its own social forum – think Facebook Wall. This is a place where users will go to post comments or ideas, ask questions, or even raise support tickets. Depending on a user’s role, they should get different views of the forums. The administrator of an API, for example, should see access requests and unanswered trouble tickets that would be invisible to regular users. The administrators would use the forum as a central place to manage the workflow of access requests and trouble tickets, and to make sure that any questions and comments are being answered.

This is a key concept - it’s not necessarily up to the administrators to answer questions and even tickets themselves. As the community around a resource matures, it will likely become more and more self-sufficient, with many questions and comments being answered by other users.

Following & User Dashboards

A standard old forum is a bit passé these days. Your enterprise API platform needs to be far more social. It should implement a Twitter-like following dashboard allowing users to follow APIs, apps, businesses, groups, or other users. Each user should have their own dashboard – like a Facebook news feed – to aggregate discussion items and comments from resources the user is following. This gives users a centralized place to keep track of what’s going on based on their interests.

Supporting Your App Developers

One of the bigger challenges you’ll face with your API is potentially becoming a victim of your own success. What’s going to happen when you drive massive social adoption of your APIs? How on earth are you going to manage the volume of support requests and questions?

Again, your enterprise API platform will have the answers. The first thing, of course, is to make sure that your APIs are 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 then publish and promote these with your APIs. But the real beauty kicks in when your developer community becomes self-sufficient and users start helping each other out by answering questions and even responding to trouble tickets.

When everything is efficiently indexed, it should be easy for users to search for errors, issues, and get immediate answers to 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.”

Manage APIs For B2B 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 businesses use to share specific functions or data with one or more partners.

A good enterprise API platform will enable this by introducing 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 integrate with several partners. Yet, you don’t want any of the partners to know about each other, or even to know that there are other partners using the API. An enterprise API platform will allow 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 thereby won't be visible to users who have not been specifically invited. In this mode, user posts, discussions, and comments would be visible only to approved users and API administrators.

Read More >>  What Is API Integration?

Another common requirement for private APIs is the need to create an API that is visible and consumable by a defined 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 of these capabilities sound great, but the success of your API initiative depends very much on your ability to get your APIs 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 developers might also use?

Your enterprise API platform should support the concept of API provider federation to bring together communities giving developers access to any APIs from any provider using a single app ID. In addition, you should allow providers to leverage the network effect of all the connected communities to find the broadest possible reach for their APIs. All this can be achieved with federated trust and permission models, allowing API providers to opt in or out at granular levels. And to choose the partners with whom they wish to federate.

Read More in Our White Paper >> Federated Architecture For Enterprise API Management

An enterprise API platform offered as a service, as well as via on-premise or hybrid models provides a ready-made community for its customers to connect with. This is true whether they choose to become a user of the Platform-as-a-Service or install the product in their own datacenters. Customers should be able to choose how much or little sharing they do with the broader community, depending largely on how open they view their APIs.

The Akana Enterprise API Platform

Akana built its Enterprise API Platform to accelerate the API economy. We do this by helping developers collaborate around and manage APIs in complex environments. Akana provides a secure and robust platform that companies can use to share their APIs with the developer community of their choice. The API Platform manages, monitors, and secures APIs, ensuring that they deliver the level of service customers and partners require. It provides security around the enterprise and customers, information and assets. This is the cornerstone of corporate brand integrity.

The Akana API management platform brings API providers and app developers together in a community that will be familiar to anyone who spends time on popular social networks.

It provides a connecting point where you can publish, promote, and manage your APIs in a secure and scalable environment. You can manage your own developer community, or just plug into communities that already exist. Creative developers can find and harness your APIs, blending them with complementary APIs from your partners. These developers can then work together, share ideas, and support each other in new and productive ways.

The Akana platform provides lots of social goodness, without losing sight of your day-to-day API management and application needs.

Our API platform stands on the shoulders of a rich heritage – Akana has been around the block a few times. We work with many of the Fortune 1000, meeting the needs of demanding production environments for their API Management.

Full API Lifecycle Management

The API Management Platform enables the full API lifecycle from planning and development, to operations and community management, all to help you build the right APIs, run them soundly, and share them with the your developer communities.

Enterprise-Class

Akana meets enterprise requirements including security, integration with existing infrastructure, performance and reliability, and much more. It offers integration with enterprise identity and security infrastructure, enabling API security models including OpenID (OIDC) and OAuth. This ensures app developers and end users remain subject to existing security and privacy policies and requirements.

App-Centric APIs

Akana provides sophisticated-yet-simple security capabilities that allow API providers to control and monitor an app’s usage of their APIs.

Policy-Driven

The Akana platform defines all security and quality of service through centrally-managed policies, ensuring consistency between multiple API implementations and versions.

APIs, Your Way

Akana allows you to define and manage your APIs using a wide range of messaging types and formats including REST/XML, REST/JSON and SOAP. You can create an API with multiple interfaces using different standards and different security mechanisms with no extra effort.

Start From Scratch, Use What You Have, Or Both

In addition to exposing new capabilities, you can leverage Akana to harness existing investments in web services and enterprise architecture, with new formats and policies specific to an outside developer group.

Experience the Akana Portal

See how easy it is to create, document, test, publish, and market your APIs in the Akana API platform with a free 30-day trial.

Start Trial

Watch Demo First 

Note: This blog post was originally published as a white paper in May 2015 and has been updated for accuracy and comprehensiveness.