Understanding Business Logic Modules versus Storage Modules

When you start using APIs to query for data, you will run into situations where you have to choose which API to use from different APIs that seem very similar to each other in name - for example, if you want to find item records, there are two potential APIs you could use:

GET /inventory/items
GET /item-storage/items

So how do you know which one to use for your use case?

Introduction

Some FOLIO modules provide different types of APIs that can appear to do similar things. You'll hear them referred to as storage APIs versus business logic APIs.

For example, when you begin exploring Inventory, you'll see two backend modules:

• mod-inventory: https://dev.folio.org/reference/api/#mod-inventory
• mod-inventory-storage: https://dev.folio.org/reference/api/#mod-inventory-storage

In this example, mod-inventory-storage is the set of storage APIs for inventory, and mod-inventory is a business-logic set of APIs that the Inventory module uses.

Are there always storage modules and business logic modules for each app?

No. Much of the structure of these modules is a matter of project historical design choices and practices, so it is really important to know that you can't always be certain that a particular app works this way. But many of the most frequently-used apps and "heaviest-used" apps, like Inventory, have this structure.

A storage API is provided by a storage module; a business logic API is provided by a business logic module.

Some general statements about storage modules:

• Storage modules abstract the storage technology. In other words, you don't need to know what kind of database is in your FOLIO tenant in order to be able to access the data.
• Storage modules .represent the source of truth for a record. For example, you may find copies of item information in other modules like mod-courses or mod-circulation-storage, but the source of truth for the item record is mod-inventory-storage.
• Storage modules do not have dependencies on other FOLIO modules, but other FOLIO modules often have dependencies on them.
• Storage modules tend to be the place where batch APIs are implemented, in cases where batch APIs have been implemented.
• Storage modules publish messages about record changes, when those workflows have been implemented.

Some general statements about business logic modules:

• Business logic modules often depend upon multiple other FOLIO interfaces and modules, and depend upon storage modules for persistent storage. E.g., mod-inventory (business logic) depends on mod-inventory-storage (storage) for the data that it primarily uses.
• Business logic modules access and aggregate data across multiple storage modules. For example, mod-circulation (business logic) talks to Users, Inventory storage, and Circulation storage in order to do its work.
• Business logic modules have APIs that can implement logic across modules and hide details about underlying structure in doing so. E.g., you would not necessarily know in using the check-out-by-barcode API that that API is talking to data in Inventory, Users, and Requests in addition to circulation.
• Business logic modules may lack functionality that is provided in a storage module. For example, as of Morning Glory, there are no APIs provided in mod-inventory that allow you to retrieve holdings records. This is because there has not been a business workflow yet that has required that that API be built. But in mod-inventory-storage, you can find an API that lets you retrieve holdings from holdings-storage directly.

The most important question: how do I choose which API to use?

It's not possible to give a blanket rule for every scenario, but here are the things you could use to try to figure out which API is best:

• Does the API exist? It's a basic question, but it is where you should start - does the API you need to use exist? If it does, are there similar APIs in both the storage module and the business logic module? If you only find an API in one module, that is probably the one you should use.
• Which API does FOLIO use in the user interface? If you are trying to replicate a transaction that happens in the FOLIO user interface,  you probably want to start with the API that the user interface uses. To figure that out, you would carry out the transaction in FOLIO while viewing the backend traffic with Chrome developer tools. In developer tools, you can find the query that's being used. Using Developer Tools definitely has a learning curve - we say that not to dissuade you, but to reassure you that if you start exploring it and are not sure what you are looking at,  you are definitely not alone. See Intro to Developer Tools in Google Chrome for more information.
• Am I trying to get information that depends on FOLIO calculating or combining values and/or records ? For example, if you are wanting to use Postman to query for users with a certain amount of fines, you probably want to use business-logic APIs, since they will often be the APIs that FOLIO itself uses to make calculations. 
• If I want to send data to a storage API, do I have a good understanding of the ramifications? There may be times when you want to go straight to the storage API, even though there are business logic pieces that you would be missing. For example, you may find that if you are migrating a large amount of data in an area where bulk APIs don't yet exist, that going directly to the storage API gives you significantly faster performance. For your library, that may be a reasonable and appropriate decision - but you then need to make sure you understand what business logic was skipped, since you may need to recreate that business logic separately in order for FOLIO to operate as expected.
  • A common example for this is migrating loans- if you are migrating a large number of loans directly to the storage API, you would need to create the notices for those loans separately. See Loans - Considerations for Data Migration for a writeup of what to consider.
• Experimentation: When in doubt, try both APIs and test the results, and examine which better suits your business need(s).
• Experience: This is more of a statement than a question, but essentially, the more experience you have with FOLIO, the more confident you will get in figuring out which APIs are best for the information that you need. This is where we encourage you to ask for advice  - questions about which API to use are very appropriate for the #learning-apis Slack channel, where you will find many community members at various stages of learning who will be willing to help.