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!