When it comes to development, we have had coding standards for almost as long as we have been coding. We tend to look at coding standards for purposes of helping to promote good quality code and reduce the likelihood of bugs and so on. But they also help with readability, making it easy to navigate a code base and so on. This is sufficiently important that there is a vast choice of tools to help us ensure we align with good practices.
That readability etc, when it comes to code interfaces lends to making it easier to use an interface as it promotes consistency and as Don Norman would say avoids ‘cognitive load‘, in other words, the effort involved in performing actions with the interface. Any Java Developer will tell you, want to print out an object (any object) you get a string representation using the .toString() method and direct it using the io packages.
That consistency and predictability are important not just for code if you look at any API best practises documents you’ll encounter directly or indirectly the need to use conventions that drive consistency – use of singular or plural for the name of entities, application of case – camel case, snake case etc. Good naming etc and we’ll see related things appear together in the documentation. Products such as Apiary and SwaggerHub include tooling to help police this in our API design work.
But what about policies that we use to define how an API Gateway handles the receipt and routing of API invocations? Well yes, we should have standards here as well. Some might say, governance gone mad. But gateways are often shared services, so making it easy to see and logically group APIs together at very least by using a good naming convention will help as a minimum. If API management is being administered in a more DevOps fashion, then information security professionals will probably want assurance that developers are applying policies in a recommended manner.
So can API policy development standards be applied? With Azure you’d need to produce an XML Parser. For Oracle’s API Platform – we can retrieve the API configurations using its own APIs and evaluate the policy JSON definition. This is precisely what’ve built here. Patterned on our other Oracle API Platform utilities, it is produced using Groovy (making it pretty easy to extend quickly, whilst getting all the benefits from Java).
The utility currently looks at naming conventions and checks them against regular expressions (Java Regex) for APIs, Plans, Applications and Services. The regular expressions are defined via a properties file so you have space to define complex expressions.
In addition to the naming conventions, it is possible to define what API Policies are mandatory for Responses and Requests, this includes referencing any custom policies.
When something is found to be non-compliant the details are written to a report file. If the tool is switched to verbose mode (DisplayAll) it will also share the information directly to the terminal.
In the GitHub repo, we have included a readme with an explanation of all the possible parameters. As before the secrets are provided via the command line, so the utility includes a -h option to get it to display the parameters. Plus the repo includes sample bat file to illustrate the parameters.