[FOLIO-490] Convention for paths of storage and business logic resources Created: 01/Mar/17  Updated: 02/Sep/21  Resolved: 02/Sep/21

Status: Closed
Project: FOLIO
Components: None
Affects versions: None
Fix versions: None

Type: Umbrella Priority: P3
Reporter: Marc Johnson Assignee: Jakub Skoczen
Resolution: Won't Do Votes: 0
Labels: question, spike, sprint10, sprint11, sprint12, sprint13, sprint9
Remaining Estimate: Not Specified
Time Spent: 2 hours
Original estimate: Not Specified

Issue links:
Relates
relates to FOLIO-519 where to keep module development guid... Open
relates to CIRCSTORE-2 Rename loan storage module to circula... Closed
Sprint:

 Description   

We are starting to build more storage and business logic modules, it seems like a good time to talk about establishing a convention for addressing them.

Given that we will likely be expressing similar resources in both the storage and business logic technical contexts, I'm referring to whether we use the top level path space for one or the other, or we simple partition the two with equal precedence.

As an example, let's assume that items live in both the business logic space and the storage space. Both need to be addressable distinctly and we could use either a hierarchy or convention. Therefore I see a few broad options (including both mine and Heikki Levanto thoughts from the previous conversation):

Storage Business Logic Note
/storage/items /items Business logic has top level address precedence, hierarchical
/items /logic/items Storage has top level address precedence, hierarchical
/storage/items /logic/items Partitioned, with no precedence, hierarchical
/items-storage /items Business logic has top level address precedence, naming convention
/items /items-logic Storage has top level address precedence, naming convention
/items-storage /items-logic no precedence, naming convention

Questions

  • Which, if any, of storage or business logic interfaces should get precedence for top level addresses, e.g. /items ?
  • Do we want either (or both) storage or business logic interfaces to have contextual grouping, .e.g. /inventory/items ?
  • What prefix / postfix name or sub-path could we use for storage or business logic ?

This started as a conversation on [DMOD-160].



 Comments   
Comment by Heikki Levanto [ 01/Mar/17 ]

At the moment, Okapi will have problems to route /items and /items/storage to different modules. We are about to resolve that ( OKAPI-274 Closed ), but even so, I feel uneasy about this. Even more so about /storage/items and /storage/users and /storage/whatever all being different modules.

Comment by Mike Taylor [ 01/Mar/17 ]

Well, Heikki – is your uneasiness based on the implementation issues that we may have? Or is it a deeper, conceptual issue?

Comment by Marc Johnson [ 01/Mar/17 ]

Heikki Levanto

does that mean you would be equally uneasy with /logic/users and /logic/inventory/items or /logic/items for business logic interfaces?

Comment by Jakub Skoczen [ 02/Mar/17 ]

Guys,

Other than a stylistic quality what would be the benefit of grouping things under /storage rather than qualifying this in the module name, e.g /users-storage. Are we sure that there is going to be a hard cut difference between storage and bl modules?

Comment by Marc Johnson [ 02/Mar/17 ]

Jakub Skoczen Heikki Levanto

I don't think there is a lot of practical difference between /storage/items, /items-storage or /item-storage/items (I personally prefer 1 or 3). The value of it being expressed in a path, is that it creates an explicit grouping. This might be far less useful if we don't want to categorise interfaces as either for storage or business logic.

What might it look like for interfaces to not be distinguished as storage or business logic? Could we have only a single resource for a conceptual idea, e.g. only one definition of an item, user or loan? Could it be that we differentiate between them using some other property?

We currently have resources with the same conceptual name (e.g. user or item) that we need to be able to differentiate between due to the same domain concept being modelling as a storage resource and business logic resource. At the moment, we make this differentiation differently, It might be valuable to have a convention so that an observer is able to easily distinguish between them.

The only property of the resources that I'm aware of in the current examples we have, is whether an interface is intended to be for storage or business logic, it may well be that there are more sensible distinguishing properties, e.g. domain context (/circulation/loan for example).

Alternatively, if we envisage that a particular named concept will only be expressed once (which is how I interpret the potential for not distinguishing between storage and business logic interfaces) then this challenge goes away.

Hugs,

Marc

Comment by Heikki Levanto [ 03/Mar/17 ]

@Mike - The implementation issue is one of the reasons for my unease, but I also feel that it would be cleaner if every module would have its own path prefix. I see it as cleaner design, and less risk of accidental collisions.

I also believe that the division to storage and business logic will get muddled up when we get more modules. We already have UI modules, and I am sure we will get more types as time goes by (gadgets, connectors, etc). In some cases there may be several layers of logic... That's why I don't like /storage/users, and that kind of schemes.

So, my personal prefernce would be to have the module that the UI is most likely to be interacting with having the most generic path prefix. For example the users business logic module could take /users. The modules it needs to support its functionality could have related paths, like /users-storage (and /users-calculations, /users-commentary, /users-whatever...). This might even extend as far as /users-permissions, although I don't have anything against a plain /permissions.

Comment by Mike Taylor [ 03/Mar/17 ]

I also believe that the division to storage and business logic will get muddled up when we get more modules.

That certainly seems possible. I agree that, this early in the game, with so many more modules to be created, we should be careful about locking ourselves into a routing convention that may look silly down the line.

So, my personal prefernce would be to have the module that the UI is most likely to be interacting with having the most generic path prefix. For example the users business logic module could take /users.

This sounds right to me. I have a bit of a horror of the -bl suffix, and find myself imagining a world where new developers come into the FOLIO world asking "Why do all the module names end with -bl" only to be told "They just do, that's how it is".

So I guess I am wholly in agreement with Heikki's suggestion. Each module (or more precisely each interface, as multiple modules can implement the same interface) should own a single top-level route, and do all their business within that area; and related modules should have related top-level routes, as in /inventory and /inventory-storage.

Comment by Marc Johnson [ 03/Mar/17 ]

Mike Taylor Heikki Levanto

Ok, if I were to try to express this convention, it could be:

  • Every interface has a globally unique top level path (e.g. /inventory, /loan-storage )
  • The interface most likely to be used by the UI (typically a business logic module at the moment) would be named after the concept being modelled (e.g. /users, /items )
  • Concepts being modelled could be grouped by context (e.g. /inventory/items, /circulation/loans )
  • Where a concept is modelled in another interface (e.g. storage modules), it will have a related yet different top level path (e.g. /item-storage/items, /loan-storage/loans )

Does that express the convention we are talking about?

Hugs,

Marc

Generated at Thu Feb 08 23:06:11 UTC 2024 using Jira 1001.0.0-SNAPSHOT#100246-sha1:7a5c50119eb0633d306e14180817ddef5e80c75d.