(taken from an excellent thread with information from Marc Johnson in #learning-apis: https://folio-project.slack.com/archives/CQ7EK52LB/p1670541286103629)
Introduction
When you start using APIs to query for data, you will run into situations where you have to choose which API to use.
Some FOLIO modules provide different types of APIs that can appear to do similar things. You'll sometimes 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.
Some general statements about storage modules:
- Storage modules abstract the storage technology. In other words, you don't need to know if your FOLIO is using Postgres or another type of database in order to query 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 implementation module for batch APIs, when those are available.
- 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 depends on mod-inventory-storage for the data that it primarily uses.
- Business logic modules access and aggregate data across multiple storage modules. E.g., mod-circulation talks to Users, Inventory storage, and Circulation storage.
- 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 potentially talking to data in Inventory, Users, and Requests.
- 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 important - 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?
- 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.
- 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.
- Experimentation: When in doubt, try either API and look at the results, and examine which better answers your question.
- 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.