API RULES vs Description

Not too long ago in web development, there was a framework called Drools which provided a standardized way to manage all your RULES for your application in one place:

• how to access
• who is allowed to access
• what params must be provided to access

This became a standard for alot of enterprises as it provided a way to put all security and access related data in one place.

Then came swagger / openapi. Many people TREAT these as RULES files but there is no enforcement or association of RULES with endpoints it is purely a descriptive document.

OpenApi / Swagger : Description Documents

First, we need to acknowledge that OpenAPI is not a RULES document and hear from the lead maintainer of the project as to what it IS:

By stating there are no ROLES (or shared state), Darrel Miller acknowledges that OpenAPI does NOT check:

• sent JWT token roles
• sent request params and returning response params
• assign ROLES to extended behavior (ie batching)

OpenAPI is derived from Swagger which was designed ONLY for apidocs. OpenAPI extends Swagger slightly to allow for testing. But they do not store endpoints ROLES showing who can access a stated endpoint and how it is accessed. This is where their testing fails 100% of the time.

Because OpenAPI does not focus on being a RULES document, it can only be used as a ‘connector’ for PUBLIC apis.

RULES files

By comparison, tools like the spring-boot-starter-beapi have shown a better approach by using JSON Schema files to describe each SET of endpoints and the RULES for access. For example:

"show": {
 "METHOD": "GET",
 "DESCRIPTION": "Description for show",
 "ROLES": {
  "BATCH": ["ROLE_ADMIN"]
 },
 "REQUEST": {
  "permitAll": [],
  "ROLE_ADMIN": ["id"]
 },
 "RESPONSE": {
  "permitAll": ["username", "email"],
  "ROLE_ADMIN": ["id", "version","firstName","lastName", "enabled", "accountExpired"]
 }
},

In the above example for the endpoint ‘user/show’, we show several different RULES:

• batching can only be done by ROLE_ADMIN
• ROLE_ADMIN can send an ‘id’ param whereas this is derived from PRINCIPAL for everyone else
• ROLE_ADMIN get extended dataset

These are ‘ACCESS RULES’ commonly referred to as RBAC and ABAC… which OpenAPI does not address.

Conclusion

OpenAPI has stated time and again that the main uses for their tool are documentation and testing and NOT as a connector.

Connectors will include RULES for access whereas OpenAPI does not; it is merely a descriptive document severely limited in its security capoabilities.