Design API endpoints and data payload for cost-per-use

MODKBEKBJ-481 - Getting issue details... STATUS

IN PROGRESS

Participants:

Role	Name	Approval
Solution Architect
Java Lead
Product Owner

Goal: provide clarity of kb-ebsco-java URLs and payloads.

Proposed Design

A mapping between kb-ebsco-java endpoints and APIGEE

Method	kb-ebsco-java	APIGEE	Cost-Per-Use
GET	/eholdings/packages/{packageId}/costperuse	GET /uc/costperuse/package/<package_id>	/api/costperuse/package/{listId}
GET	/eholdings/packages/{packageId}/titles/costperuse	POST /uc/costperuse/titles	/api/costperuse/titles
GET	/eholdings/titles/{titleId}/costperuse	GET /uc/costperuse/title/<title_id>/<package_id>	/api/costperuse/title/{kbid}/{listId}
GET	/eholdings/resources/{resourceId}/costperuse	GET /uc/costperuse/title/<title_id>/<package_id>	/api/costperuse/title/{kbid}/{listId}

kb-ebsco-java endpoints details

Method	kb-ebsco-java	Parameters	Description	Permission
GET	/eholdings/packages/{packageId}/costperuse	platform = [PUBLISHER, NO_PUBLISHER, ALL ] fiscalYear = <year>	Retrieve consolidation information for a particular package	"kb-ebsco.packages-costperuse.item.get"
GET	/eholdings/packages/{packageId}/titles/costperuse	platform = [PUBLISHER, NO_PUBLISHER, ALL ] order=<ASC, DESC> page=<integer>	Retrieve consolidation information for titles included to a package	"kb-ebsco.packages.titles-costperuse.item.get"
GET	/eholdings/titles/{titleId}/costperuse	packageId=<package_id> platform = [PUBLISHER, NO_PUBLISHER, ALL ] fiscalYear = <year>	Retrieve consolidation information for a particular title	"kb-ebsco.titles-costperuse.item.get"
GET	/eholdings/resources/{resourceId}/costperuse	platform = [PUBLISHER, NO_PUBLISHER, ALL ] fiscalYear = <year>	Retrieve consolidation information for a particular resource	"kb-ebsco.resources-costperuse.item.get"

mod-kb-ebsco-java Data Structure

Method Image Sample data response

GET /eholdings/packages/{packageId}/costperuse 
+ 
GET /eholdings/packages/{packageId}/titles/costperuse

GET /eholdings/packages/{packageId}/costperuse

{
  "data": [
    {
      "type": "packageCostPerUse",
      "attributes": {
        "platforms": [
          {
            "name": "InjentaConnect"
          },
          {
            "name": "Proquest"
          },
          {
            "name": "Willey Interscience"
          },
          {
            "name": "Willey Online Library"
          }
        ],
        "analysis": {
          "publisherPlatforms": {
            "cost": 5175,
            "usage": 6149,
            "costPerUse": 0.8416002602
          }
        }
      }
    }
  ]
}

GET /eholdings/packages/{packageId}/costperuse/titles

{
  "data": [
    {
      "type": "packageTitleCostPerUse",
      "attributes": {
        "resources": [
          {
            "id": "1-473-356",
            "attributes": {
              "cost": 141.8806,
              "usage": 26,
              "costPerUse": 5.456946153846153,
            }
          },
          {
            "id": "5-473-491",
            "attributes": {
              "cost": 100.0,
              "usage": 15,
              "costPerUse": 6.666666666666667,
            }
          }
        ]
      }
    }
  ]
}

To calculate a "Package cost" for packages with a large number of titles we may use data stored in mod-kb-ebsco-java 'holdings' table and return results by pages where default value is 25 and the max value is 100. example

/eholdings/packages/{packageId}/titles/costperuse?page=1&order=ASC

'Package Cost' value may not always be present in the response from APIGEE, in this case, the 'Package Cost' value should be calculated by retrieving all individual titles and sum up costs.

GET /eholdings/titles/{titleId}/costperuse

{
  "data": [
    {
      "type": "titleCostPerUse",
      "attributes": {
        "platforms": [
          {
            "name": "InjentaConnect",
            "isPublisherPlatform": "true",
            "counts": [60, 55, 50, 110, 65, 50, 50, 100, 50, 130, 68, 56],
            "total": 844
          },
          {
            "name": "Proquest",
            "isPublisherPlatform": "false",
            "counts": [75, 80, 80, 105, 85, 75, 75, 75, 75, 100, 75, 75],
            "total": 975
          },
          {
            "name": "Willey Interscience",
            "isPublisherPlatform": "true",
            "counts": [40, 40, 40, 90, 50, 25, 22, 30, 24, 60, 40, 20],
            "total": 481
          },
          {
            "name": "Willey Online Library",
            "isPublisherPlatform": "true",
            "counts": [50, 60, 61, 89, 80, 65, 75, 55, 80, 120, 80, 85],
            "total": 900
          }
        ],
        "analysis": {
          "publisherPlatforms": {
            "cost": 800.00,
            "usage": 2225,
            "costPerUse": 0.359550561797753
          },
          "nonPublisherPlatforms": {
            "cost": 500.00,
            "usage": 900,
            "costPerUse": 0.555555555555556
          }
        }
      }
    }
  ]
}

"Platform usage" values for "Total for all publisher platforms" can be found by adding the parameter 'aggregatedFullText' = false, means that "Publisher" = true

"Total for all non-publisher platforms" by 'aggregatedFullText' = true, means that "Publisher" = false

"Cost" for "Total for all publisher platforms" and "Total for all non-publisher platforms" is to be defined because currently there is no difference for the value analysis.current.cost returned in both cases 'aggregatedFullText' = false,'aggregatedFullText' = true

GET /eholdings/resources/{resourceId}/costperuse

aggregatedFullText=false

{
  "data": [
    {
      "type": "resourceCostPerUse",
      "attributes": {
        "platforms": [
          {
            "name": "InjentaConnect",
            "counts": [60, 55, 50, 55, 65, 50, 50, 100, 50, 130, 68, 56],
            "total": 789
          },
          {
            "name": "Willey Interscience",
            "counts": [75, 80, 80, 105, 85, 75, 75, 75, 75, 100, 75, 75],
            "total": 975
          },
          {
            "name": "Willey Online Library",
            "counts": [40, 40, 40, 90, 50, 25, 22, 30, 24, 60, 40, 20],
            "total": 481
          }
        ],
        "analysis": {
          "publisherPlatforms": {
            "cost": 800.00,
            "usage": 2225,
            "costPerUse": 0.359550561797753
          }
        }
      }
    }
  ]
}

Implementation stories:

Consolidation information at resource level - MODKBEKBJ-497 - Getting issue details... STATUS

Consolidation information at title level - MODKBEKBJ-498 - Getting issue details... STATUS

Consolidation information at package level - MODKBEKBJ-499 - Getting issue details... STATUS

Consolidation information at package-title level - MODKBEKBJ-500 - Getting issue details... STATUS