API Productization Best Practices

Not applicable

We’re putting together a plan for finalizing our Dev Portal / Developer Experience and were wondering if you could offer guidance / best practice recommendations?

Essentially our goals are to:

  • Create clean “API products” that both limit endpoint access to specific audiences, as well as make our documentation easy to understand and read.
  • Reference “API products” by specific names for marketing & training purposes

So for example, I want us to have “API products” such as:

  • Our Affiliate Network API – Used by 3rd parties with large consumer bases that want to display our inventory.
  • Our Business API – Used by our customers to create their own back office systems.
  • Our Client Engagement API – Used by our customers to create consumer facing websites of their own to interact with their clients.

Now the thing is… some of these “API products” will likely encapsulate the same endpoints… All 3 API Products might need a “Get Addresses” call, for example.

So our question is… What is the best strategy for this in order to maximize reusability and minimize redundant configuration? A few considerations that are top of mind are:

  • 1.Should each “API Product” be its own proxy? (we don’t think this is the case)
  • 2.Should we have multiple “API Products” that each reference just one proxy… and then specify which endpoints each product has access to? (we are leaning towards this approach)

Followup question for question #2

  • What configurations do we make in our developer portal to limit which documentation specific audiences have access to? (so for example, if Developer A has access to the Affiliate Network API, how can we show him Affiliate Network API documentation, but ensure they can not see Business API documentation?)

Thanks!

1 1 1,021
1 REPLY 1

Not applicable

I agree with your perspective on 1-3 regarding products as a general approach. No need to have a separate proxy/virtual host for each product unless there's something specific you're trying to accomplish (and even then it would take some convincing).

For restricting access by role I have two things that may come in handy. First, if you're interested in controlling self-service access to APIs by role (e.g. only affiliate users can request an API key for the affiliate product) you can enable the included "DevConnect Limit API Product by Role" module in the administrative Modules section. This will create a new admin menu option under Configuration -> Dev Portal called "API Product Role Access". If you are creating SmartDocs for your API and want to limit access to the API based on user role, take a look at the article that @Chris Novak wrote on this subject.

Hope this helps!