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)

{
  "id": "mod-hello-foo-1.0.0",
  "name": "Hello foo module",
  "provides": [{
    "id": "distributed_configuration",
    "version": "1.0",
    "namespace": "foo",
    "handlers": [{
      "methods": [ "GET" ],
      "pathPattern": "/configurations/entries",
      "permissionsRequired": [ "foo.configuration.entries.collection.get" ]
    },
    {
      "methods": [ "GET" ],
      "pathPattern": "/configurations/entries/{id}",
      "permissionsRequired": [ "foo.configuration.entries.item.get" ]
    },
    {
      "methods": [ "POST" ],
      "pathPattern": "/configurations/entries",
      "permissionsRequired": [ "foo.configuration.entries.item.post" ]
    },
    {
      "methods": [ "PUT" ],
      "pathPattern": "/configurations/entries/{id}",
      "permissionsRequired": [ "foo.configuration.entries.item.put" ]
    },
    {
      "methods": [ "DELETE" ],
      "pathPattern": "/configurations/entries/{id}",
      "permissionsRequired": [ "foo.configuration.entries.item.delete" ]
    }]
  }],
  "requires": [],
  "launchDescriptor": {
    "exec": "node hello_foo.js"
  }
}

Example (Consumer)

"requires": [
  {
    "id": "distributed_configuration",
    "version": "1.0"
    "namespace": "foo"
  }
]

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.
• 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
  • Option B - as a new query argument, e.g. GET /configuration/entries?namespace=foo

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

1. Do we want/need to incorporate version into the discriminator too?  This is something that came up in the JIRA comments here.
2. Do we even want to support RAML?  If OpenAPI is the way forward, maybe we skip defining it in RAML...
   1. Has a way of sharing common API definitions/traits been sorted out yet on the OpenAPI side of things?
   2. Is the expectation that all modules will eventually move towards OpenAPI?  Even those which currently use RAML?

JIRAs

• UXPROD-3018 - Getting issue details... STATUS
• FOLIO-3105 - Getting issue details... STATUS
• FOLIO-2875 - Getting 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)