Hi all,
I would like to present the following proposal regarding support for
multiple independent REST-APIs.
This opens up an idea already discussed some years ago in this ticket:
https://issues.apache.org/jira/browse/OFBIZ-12033
The ticket for this proposal can be found here:
https://issues.apache.org/jira/browse/OFBIZ-13440
Looking forward to hearing your thoughts:
In more complex project scenarios, it can be necessary to host more than
one independent REST API with different credentials, authorization
rules, and security groups.
Typical examples include connecting different applications or external
integrations, where each integration should have its own API boundary
and security configuration.
Each independent REST API should have:
Its own API group and routing context.
Its own configurable authorization/security groups.
A separate verification/authentication endpoint, where required.
Its own OpenAPI specification containing only the endpoints belonging to
that API.
Its own Swagger UI displaying only the endpoints belonging to that API.
A clearly distinguishable URL structure.
Proposal
The REST API plugin in its current form is well suited for this
improvement. A first implementation plan looks roughly as follows.
1. Introduce apiGroup in rest.xml
Add a new apiGroup parameter at the <api> level in rest.xml.
The apiGroup parameter defines the logical API to which the REST
endpoints belong and effectively replaces the current <api>-level path
as the mechanism for separating API groups.
For backwards compatibility, <api> definitions that do not explicitly
declare an apiGroup should be assigned a default group, for example:
api
This allows the available REST endpoints to be separated into
independent API groups without requiring every existing API definition
to be changed.
For example, suppose the current endpoints are:
/rest/users
/rest/users/1000
/rest/products/create-product
/rest/testService
We now want to separate the user- and product-related endpoints.
This could be achieved by defining the corresponding apiGroup values in
rest.xml:
apiGroup="usermanagement"
apiGroup="webshop"
The resulting endpoints would become:
/rest/usermanagement/users
/rest/usermanagement/users/1000
/rest/webshop/products/create-product
/rest/api/testService
testService has no explicitly defined apiGroup and therefore remains in
the default api group.
This provides a clear routing boundary between the different APIs.
2. API-specific authentication and authorization
The separation of API groups should also allow authentication and
authorization to be configured independently.
For example, instead of having one universal authentication endpoint:
/rest/auth/token
an authentication endpoint could be provided for each API group:
/rest/usermanagement/auth/token
/rest/webshop/auth/token
/rest/api/auth/token
Each API group could then be associated with its own configurable
security groups and credentials.
Alternatively, the existing authentication service could remain
centralized and accept an optional apiGroup parameter when generating a
token.
For example:
/rest/auth/token?apiGroup=usermanagement
/rest/auth/token?apiGroup=webshop
This would retain a single authentication endpoint while still allowing
generated tokens to be associated with a specific API group.
3. API-specific OpenAPI specifications
Each API group should have its own OpenAPI specification.
For example:
/rest/usermanagement/openapi.json
/rest/webshop/openapi.json
/rest/api/openapi.json
The generated specification should contain only the REST resources
belonging to the corresponding API group.
The OpenAPI document itself should represent the API boundary.
Conceptually:
/rest/usermanagement/openapi.json
only usermanagement schemas/operations
/rest/webshop/openapi.json
This separation should be implemented at the OpenAPI generation level
and NOT!! by filtering the final JSON response.
4. API-specific Swagger UI
Swagger UI should be relatively straightforward to adapt.
Currently, navigating to something such as:
.../docs/swagger-ui.html
causes Swagger UI to request the OpenAPI specification, for example:
/rest/openapi.json
The OpenAPI resource then generates/returns the specification.
With API groups, Swagger UI could instead be associated with a specific
API group:
.../docs/usermanagement/swagger-ui.html
.../docs/webshop/swagger-ui.html
which would load:
/rest/usermanagement/openapi.json
/rest/webshop/openapi.json
Each Swagger UI would therefore display only the endpoints belonging to
its respective API group.
The Swagger UI itself does not need to contain the API-group logic; it
simply needs to be configured to load the appropriate OpenAPI specification.
5. Routing context
The API group should be distinguishable through its routing context.
For example:
/rest/usermanagement/...
/rest/webshop/...
/rest/api/...
This provides a clear and consistent boundary between APIs and makes
them possible to independently configure
--
Lukas Finster
Softwareentwickler & Berater
ecomify GmbH, Stralsunder Straße 63, 33605 Bielefeld
Fon: +49 521 448157-90 | Fax: +49 521 448157-99 | www.ecomify.de
Court Registration: Amtsgericht Bielefeld, HRB 41683 | CEO: Martin Becker,
Michael Brohl
