DX, API Design & Documentation

Importance of API Approval Workflows in the Path to API Governance


APIs are taking over every vertical out there with its standards, reusability and simplicity that is required to operate in the present world. However with the rise of API adoption it is also important to impose proper API governance to the processes, APIs and also to the various stakeholders of an API ecosystem. This article highlights the importance of human tasks in API governance that every growing API community should consider and adapt in their API strategy and the technologies used in API management, and what to look out for when evaluating API workflow requirements and technologies.

Diagram 1 : Internal and External API Usage of an Organization

With the current rise in the use of APIs, more and more organizations are compelled to build APIs for their value added services and  to expose these services in an uniform manner. However as the number of APIs grow along with the participants who access and use these APIs, the need for proper management and governance is required more than ever. This would mean defining boundaries, restrictions structures, permission models across the organization and these decisions may require special screening by users/humans themselves. This level of manual screening is depicted by human tasks(approvals/rejections) in workflows. A workflow in this context  is a series of steps defining a process which is executed sequentially. 

Let us take an example of an organization with multiple business units. Each of these business units will expose their services through APIs and would manage the entire API lifecycle of the APIs that they publish. This brings up  the requirements of controlling API visibility where some APIs are publicly accessible while some are not. There could be API usage across an organization (within the business units) as well as external partner based API usage.  This could mean that each business unit could be maintaining their own developer portal to advertise the APIs with respective API visibilities maintained.  When the organization decides to expose these  APIs to external partners , each  business unit API management team should carefully draft how users can sign up at each portal, which users are allowed to access and invoke their APIs, govern the API lifecycle states and more. 

Diagram 2 :  Manual Screening

This gets somewhat complicated  as you may need to to treat  these various user groups differently. Some users may need to go through less restrictions while the others go through a few more steps for additional governance. For example if we consider the user registration process, if the user registering is an employee (a member of another business unit) internal processes may require that employee to go through a manual approval process led by his/her business unit administrators. At the same time, for a generic user you might not want to impose such manual approvals at the point of registration (to improve API adoption)  but would  want to impose some manual steps  to place better control when they try to subscribe and invoke an API.

Now that there is a well defined need for manual workflows, it is important to identify potential  API specific use-cases you might encounter that would require manual governance over time. If your APIs are already monetized with a payment model, your subscribers might need to update their subscription tier based on their usage. This would be a path where better governance is required as this may involve  finance and contractual approvals in the process before a user can move to a different tier. Another such use-case would be on who/what resources can generate API tokens in order to access an API. If the API subscription model is based on applications and tokens, it is important that you impose governance on the token generation process so that you can restrict untrusted applications from generating tokens. Internal API lifecycle management is also another process that requires strict governance. Similar to various development processes,  various API states (created, published, deprecated, etc) should also be maintained by API product managers should have the autonomy to verify  which APIs are ready to be published. 

This would also help in the API versioning and retiring strategies too.

Diagram 3 : Sample API Subscription Approval Workflow

API workflow processes are inevitable when an organization’s API strategy is delved into its culture and the participants embrace API reuse. Therefore it is important to include this requirement in the overall API management strategy of an organization from the start.Most API vendors bring in API workflow features through the use of a workflow engine which could be built natively in the product or to externally configure a third party workflow engine. Although we discussed a couple of generalized use-cases they may apply with a unique set of conditions in each  and every organization as those internal governance processes are native to that organization. A core requirement of API workflow support would be extensibility. Therefore it is important that these manual task creations are easily customizable to blend in custom logics as well. These technologies should provide greater flexibility for customization as well as various output generations. For example, whenever user tasks are generated, based on the actions taken by the assigned user, those actions should be followed up with notifications. These notifications can be real-time alerts such as emails and SMS. Overall for any organization with a long term API strategy, should consider the possibility of human task approvals at an early stage, and evaluate their processes and technologies accordingly.


 –   –   –   –   –   –   –   –   –   –   –   –   –   –   –  –  –   –   –    USER STORIES  –   –   –   –   –   –   –   –   –   –   –   –   –   –   –  –  –   –   – 

As a product manager, I want to understand all aspects of the API economy and be able to refer my colleagues and staff to relevant content, techniques and technologies that will support them to do their job.

As a developer evangelist, I want to be inspired by best practices for engaging and going to my developer community so I can demonstrate my impact on our business/agency growth.

–   –   –   –   –   –   –   –   –   –   –   –   –   –   –   –   –  –  –   –   –  –   –   –   –   –   –   –   –   –   –   –   –   –   –   –   –   –   –  –  –   –   –  –   –   –

Himasha Guruge

Himasha Guruge

Associate Lead Solutions Engineer at WSO2
Himasha Guruge is a solutions engineer working closely with global enterprises on integration and messaging software projects. She is an Associate Lead Solutions Engineer at WSO2 and has worked on interesting projects in various domains assisting organizations to build API-led integrations. She is an integration evangelist, a speaker, and an author.

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture