API Developer Portal Service Catalog
April 9, 2018

Using an API Developer Portal as a Service Catalog

Developer Portal
In my opinion, a large part of the blame for why many SOA programs struggled to live up to expectations can be laid at the door of UDDI registries, and I’m not alone in that opinion. It’s pretty easy to point fingers, but a deeper look provides a lot of insight as to how to avoid these failures as we move down the path of adopting APIs as a core technology for integration – see my first post in this series.





The whole concept of the registry seems very outdated today. It’s not so much that the registry was provider-centric (one of the biggest challenges for SOA), it’s that they didn’t make it easy for consumer developers to find anything. Probably the most defining difference between an API program and an SOA initiative is in the difference between a developer portal and a UDDI registry – I’m sure lots of people will be screaming about REST vs. SOAP at this point, but that is misguided, there’s nothing to stop API programs using SOAP. This distinction between developer portal vs. UDDI registry gets straight to the heart of why APIs are popular, and why SOA isn’t.

A UDDI registry is a simple repository of technical service specifications, categorized using formal and rigid taxonomies, whereas good developer portals are consumer-centric, providing all the things needed for an app developer to easily find and use an API.

What Makes a Good Developer Portal

The goal of a developer portal is simple – as I said above, it’s all about making it easy for developers to find and use APIs. So what do you need in a developer portal to accomplish this?

Finding APIs

There are a couple of different ways of finding APIs:

  • Public/enterprise search – search engines have had a massive impact on the way we work and the idea of connecting to a special purpose system to try and find assets (services, APIs, document types, etc.) feels like it belongs in a different decade. For an externally-facing API, one of the main roles of the developer portal is to market the API, including extensive search engine optimization. This can apply to internal APIs, but only if the enterprise has an effective internal search system.
  • Portal search – in many cases, finding the right API is a question of being able to search through the hundreds or even thousands of interfaces available. The portal needs to provide filtering (by tag or taxonomy) as well as free text search of name, description, endpoint, interface, payload schema, and even discussion forums. This is much more important for internal API initiatives where there will typically be orders of magnitude more APIs than those facing external consumers.
  • Hierarchical browse - the idea of browsing through a catalog based on a formal taxonomy has become increasingly irrelevant with the power of search, especially when combined with simple filtering. However, enterprise developer portals often leverage a hierarchy to model their organization, team, and project structures both for delegated admin, and simplified access control. Some developers might only be able to see APIs defined within the scope of their project, and there may be workflow processes for API publication and consumption (see below for more on this).

NOTE: Portal search is often important even for external developer portals that leverage public or enterprise search engines, in many cases the external search will get you to the portal, but not necessarily to the specific resources you need.

Using APIs

There are lots of elements to facilitate the easy use of APIs. This post could easily grow into a massive discourse on each, so to avoid that, I will summarize the requirements here and leave scope to write focused posts with more detail on these in the future.

  • API documentation – this will definitely be the subject of a future post, but for now, let me just say that the developer portal needs to do much more than publish a technical descriptor document (OAS/Swagger, RAML, WADL, WSDL), it needs to allow API developers to provide detailed scenario documentation, descriptions of how the security model works, code samples, possibly even SDKs, and much more. It should also not be limited to just one descriptor language, it should be able to publish API specifications however the app developer wants to consume them.
  • Provisioning and access workflow – the portal should provide workflow mechanisms for approving or rejecting requests from developer to access the portal itself as well as processes for requesting app access to APIs. This is a rich topic all on its own and will again be the subject of more discussion in a future post.
  • Version and lifecycle management – over the last few years, governance has become a dirty word, especially when applied to SOA programs. Even so, the core concepts of versioning and lifecycle management remain extremely important. A good developer portal will provide control over which APIs are published, how they are published, and when and how they are versioned. It will also ensure that it presents the right version of an API to app developers and will allow developers to choose the version in which they are interested. The developer portal is a key part of the API management platform helping you make sure you build the right APIs, build them right, and in conjunction with an API gateway ensure they are running right.
  • Social interactions – given the drama surrounding social media at the moment it may seem strange to talk about the importance of social interactions in a developer portal. What this refers to, however, is the need for app developers to get help from the API provider and the broader community as they work to build applications that consume APIs. They also need the ability to follow (like Twitter) APIs and API developers to ensure that they stay informed about what’s happening with the APIs they use.
  • The developer portal needs to be strongly integrated with the gateway infrastructure hosting the APIs. This enables a number of important capabilities:
    • Key provisioning and management – API and app keys that are presented to users and used to identify apps and APIs must be shared with the gateway infrastructure.
    • Immediate configuration updates – when a user’s app is granted access to an API, the gateway needs to know that the app’s keys, secrets, certificates, etc. can be used to authenticate the app and validate contracts for access control, per app throttling, SLA management, reporting, and more.
    • Monitoring data – API and app developers should be able to see charts and reports, and access transaction and debug logs for their APIs and apps. Strong integration with the gateways allows the portal to surface real-time operational data to developers and DevOps teams.
  • Dynamic content – inside the enterprise, a developer portal will be used to support hundreds or thousands of APIs, whereas a typical externally facing portal will often have only a small handful of APIs. This means that the kinds of heavy-lifting often required to publish an API externally (this commonly involves what is essentially building a custom website for each API) is not practical. When an API developer creates an API and adds appropriate documentation, it should immediately be published (subject to workflow of course) into the portal for app developers to find and use. Content cannot be static because the volume of change will overwhelm a typical web publishing team.
    • A key part of this content worth its own mention is the documentation. API documentation should reflect the exact interface that is hosted on the gateway. Whenever an API developer publishes or updates an interface, this should simultaneously affect the actual API endpoint, and the documentation of this API. This documentation should be published in a standardized format (e.g. Swagger), ideally with a built-in test client so that app developers can experience that actual API through the documentation.
    • The sheer number of APIs and other assets that will be published through the portal means the portal UI needs to be designed for scale. Simple things, like any lists, must be generated by searches, and no lists should appear in static navigation or other static pages.

That got a bit deep and requirements-centric, I’m afraid that’s the product manager in me. The simple take away from this is that the effective use of a fit-for-purpose (see above) developer portal can make all the difference between a failed SOA initiative and a massively successful internal API program.

Stay tuned for more, including a discussion on the how API gateways are taking the role of the integration server.