To an API consumer, a great developer portal is everything. To an API provider, having a community centric developer portal is only the visible tip of the iceberg. Under the waterline are the business and IT concerns that make APIs practical to deploy and operate.
So what is a managed API? Well, a managed API is by definition â€śunder managementâ€ť đź™‚ A managed API has a well-defined interface, it has a defined target audience and it is under appropriately enforced business and IT control.
The API business owner decides:
– The plans (terms and conditions) under which the API can be consumed
– The communities that the API will be shared with
– Whether the API is currently succeeding with its objectives (if not then the business model needs adjustment)
All of which can be done without changing the API definition or implementation in any way.
IT operations must ensure that:
– The runtime(s) hosting the API can be securely and robustly operated
– That a given API is properly authenticated and that proper authorization is in place for anyone consuming it
– API traffic is optimized and prioritized according to varying business needs
All of which can also be done without changing the API definition or implementation in any way.
Note the fundamental distinction between what the API owner â€śsellsâ€ť in terms of API plan access and what the underlying infrastructure may be able to cope with. Always having spare capacity to cope with the full potential of traffic corresponding to API plans â€śsoldâ€ť can be very costly. The mechanisms to avoid prohibitive runtime cost is to either make sure that your API runtime is a highly scalable appliance (in which case actual load matters less) or alternatively apply traffic throttling if and when current load surpasses available capacity (smoothing out traffic spikes). Either way, requirements need to be raised against the capabilities of a selected API runtime.
Having addressed the concerns of the API owner and of IT operations, finally the API designer needs to be able to physically create and deploy the API:
– Define the API interface
– Discover backend endpoints that may provide the data or function required to implement the API
– Configure the mapping between the API interface and the backend sources of data or function
It is important that the API designer can do these tasks without a lot of coding. As soon as the implementation of an API becomes code intensive rather than a mere matter of dynamic configuration, the rate of innovation inevitably slows down even for the most agile of development teams. This distinction between configuring an API, and developing the backend data or function embodying that API, is fundamental to API thinking â€“ as pointed out in an earlier blog, modern APIs are not a piece of software, modern APIs are a flexible way of projecting capabilities to audiences outside your own team.
For maximum effectiveness the three roles or personas addressed here, the API owner, IT operations and the API designer, need each their own user experience design. Their concerns are sufficiently different that the tools for one persona are sub-optimal for another.