RFC: Inventory Use Cases and Draft API

[digisomni]

Please comment with potential use cases and/or considerations for an API. Simple is better for a v1.0, it's best to make this in a way that lends itself to long term evolution.

The current leading method proposed is to use a JSON bookmark style system with arbitrary data attached for things like categorization, plugins, tags, and any extra functionality that is not enforced by the schema. This allows for maximum flexibility.

The Inventory API itself does not have any upload/download for assets, it's simply a way to bookmark items for users on their accounts. An Asset API will also be developed to help ease use cases where uploading/downloading assistance is desired.

Spec

add -> pass userIdentifier, path, filename -> returns ID
remove / delete -> pass userIdentifier, path, filename -> returns bool
edit -> pass userIdentifier, path, filename OR ID and JSON object with data fields to add/remove/modify ->returns modified object data
findByName -> pass userIdentifier, filename -> returns object data
findByID -> pass userIdentifier, ID -> returns object data
findByHash -> pass userIdentifier, hash -> returns object data
findByType -> pass userIdentifier, ID -> returns object data
listItems -> pass userIdentifier, path (optional) -> returns array with each item and a JSON object with its hash and ID
listFullItems -> pass userIdentifier, path (optional) -> returns array with each item and a full JSON object for each

Are these needed? Maybe have the ability to specify what data you want on a find request.
getID -> pass userIdentifier, path, filename -> returns ID
getHash -> pass userIdentifier, path, filename -> returns hash

Item Schema

name - string
description - string
type - string
tags - array
url - string
metadata - JSON object
ID key - not editable by user - string
hash not editable by user - string - SHA256
lastEdited - date
serverItem - bool - this is to allow the server to control the item rather than the user, useful for games and activities. Only the server or an admin can toggle this.

Example

name - Sword
description - A sword that is long.
type - model
tags - ["sword", "long"]
url - https://google.com/sword.fbx
metadata

{
  "bound": true,
  "pendingTransfer": false,
  "stackable": false,
  "stats": {
    "damage": 5,
    "durability": 0.95,
   }
}

ID key - 543JFDASJ83
hash - 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
lastEdited - (Insert ISO date here, undetermined)
serverItem - true

[Misterblue]

The proposal seems to suggest a flat directory structure (like a hash bucket like S3). From managing an inventory in SL, I liked having sub-folders and the ability to search for anything. Sub-directories could be considered and the searching/filtering function should be defined generally.

Totally un structured data will be a problem in the long run. There should be a schema for some top level fields.

Also, searching around, there seems to be a distinction between "game" inventories (the contents of your backpack) which are usually a smaller collection of easy to access items, and a larger "all my stuff" inventory like in SL. How would that fit into this inventory system?

For reference:
Steam Inventory Schema: https://partner.steamgames.com/doc/features/inventory/schema

[digisomni]

I've revised it further to be more clear. It's going under the assumption that everyone's items are dumped into an S3 bucket (though this may not always be the case, it's a good baseline) and as such it requires that a userIdentifier is passed and the server will accept, deny, or alter your request based on permissions linked to your own token.