Overview
In contrast to the "Multple Interface" approach, the idea here is to use standard interfaces and extend OKAPI to support the concept of a namespace to act as the discriminator.
Namespace-scoped Interface Support
The changes required here include generic support for namespace-scoped interfaces:
Module Descriptor
- Add a new field "namespace" - this serves as the discriminator in the case when an interface which have already been defined with the same name.
- Optional
- String
- Applies to both the provides and requires sections of the Module Descriptor
Example (Provider)
Example (Consumer)
OKAPI
- Incorporate namespace into conflict check (See https://github.com/folio-org/okapi/blob/6dce782cfa47253f80c20ce8fa74c8f3d365fddc/okapi-core/src/main/java/org/folio/okapi/util/DepResolution.java#L197):
- If an interface being defined specifies the same name and/or
pathPattern
as a registered/enabled interface, check for a namespace field.- If not present, reject the module descriptor.
- otherwise, check that the interface hasn't already been defined for the specified namespace.
- If so, we have a conflict - namespace must be unique for a given interface definition.
- otherwise, allow it to be registered again in the context the namespace.
- If an interface being defined specifies the same name and/or
- Incorporate namepace into dependency checks (See https://github.com/folio-org/okapi/blob/6dce782cfa47253f80c20ce8fa74c8f3d365fddc/okapi-core/src/main/java/org/folio/okapi/util/DepResolution.java#L96):
- Incorporate namespace such that a if it's specified in the required section, the interface is registered/enabled w/ that same namespace.
- Incorporate namespace into the proxy logic. (See https://github.com/folio-org/okapi/blob/02eeac94dbf28a114ac839ebba1209dd7b97217b/okapi-core/src/main/java/org/folio/okapi/managers/ProxyService.java#L185):
- Option A - as part of the proxy path, e.g. prefix the interface path with the namespace:
GET /{namespace}/configurations/entries
- If we go this route, we might consider being explicit about the this in the
pathPattern
field
- If we go this route, we might consider being explicit about the this in the
- Option B - as a new query argument, e.g.
GET /configuration/entries?namespace=foo
- Option A - as part of the proxy path, e.g. prefix the interface path with the namespace:
Distributed Configuration Support
The work required to implement the distributed_configuration (namespace-scoped) interface:
RAML/OpenAPI
At least one user story is needed in the OKAPI project to handle the following:
- Create shared/common interface description for the distributed_configuration API.
- Incorporate the namespace query arg or path prefix (depends on the approach we take - see above)
- Should be easy to pull in and use by modules (like existing shared RAML traits, etc.)
raml-module-builder / folio-spring-base
- Create default implementations of the distributed_configuration interface
- Similar to what's currently provided by mod-configuration - probably just handles persistence, no fancy business logic required
- Can be easily overridden if desired.
Stripes Changes
- Create a new smart component for interacting with implementations of the distributed_configuration interface (See https://github.com/folio-org/stripes-smart-components/tree/master/lib/ConfigManager)
Pros/Cons
Pros
- Doesn't require use of additional X-Okapi-* headers
- Allows modules to depend on the interface
- It's use is completely optional
- Clients are not required to know/determine the module Id in order to call a specific implementation of the interface.
Cons
- More complex OKAPI logic
- ?
Other Considerations
- Do we want/need to incorporate version into the discriminator too? This is something that came up in the JIRA comments here.
- Do we even want to support RAML? If OpenAPI is the way forward, maybe we skip defining it in RAML...
- Has a way of sharing common API definitions/traits been sorted out yet on the OpenAPI side of things?
- Is the expectation that all modules will eventually move towards OpenAPI? Even those which currently use RAML?
JIRAs
- - UXPROD-3018Getting issue details... STATUS
- - FOLIO-3105Getting issue details... STATUS
- - FOLIO-2875Getting issue details... STATUS
- At least one user story for the OKAPI and ModuleDescriptor work
- One story for the RAML/OpenAPI work
- One story for the RMB work
- One story for the folio-spring-base work.
- One story for stripes-smart-components work.
- One story for a module to make use of this (Provider/BE)
- One story for a module to make use of this (Consumer/FE)