XBRCatalog about wamp-xbr

[oberstet]

Anyone (registered in the XBR network) can publish an API definition:

/**
 * Publish an API to the service API registry.
 *
 * @param api: Globally unique (and unchangeable) API ID (a 16 bytes UUID).
 * @param schema: API schema definition (required).
       IPFS Multihash pointing to a schema definition file.
 * @param terms: Optional copyright, legalese and terms (for human/developers consumption).
       IPFS Multihash pointing to a terms archive file.
 * @param docs: Optional API documentation (for human/developer consumption).
       IPFS Multihash pointing to a documentation archive file.
 */
function publishAPI (bytes16 api,
                     string memory schema,
                     string memory terms,
                     string memory docs) public;

• Once an API has been published, it is frozen: its schema definition and its terms cannot be changed anymore.
• The documentation for an API (different from the schema) can be changed after the API has been published in the first place

[oberstet]

The approach of identifiying APIs using UUIDs, and freezing APIs once published, follows established practice in eg MS COM (component object model):

The COM standard requires that an interface definition must not change once it has been published. The author cannot, for example, add a new method to an existing interface. The author must instead create a new interface. While there are no restrictions on what methods must be in that interface, a common practice is to have the next-generation interface include all the of the old interface's methods, plus any new methods. It's not unusual for an interface to have several generations. Typically, all generations perform essentially the same overall task, but they're different in specifics. Often, a COM component implements every current and prior generation of a given interface's lineage. Doing so allows older applications to continue using the object's older interfaces, while newer applications can take advantage of the features of the newer interfaces. Typically, a descent group of interfaces all have the same name, plus an integer that indicates the generation. For example, if the original interface were named IMyInterface (implying generation 1), then the next two generations would be called IMyInterface2 and IMyInterface3.

source: https://docs.microsoft.com/en-us/windows/win32/prog-dx-with-com

---

While an APIs UUID is known and published on-chain, any interface naming (such as WAMP URIs) is only part of the schema definition - which lives off-chain (as a file on IPFS or elsewhere).

[oberstet]

Since an API is frozen once published (neither its schema nor its term can change), the only data that can be update is the API documentation, for which we need to provide a public function - which can only be called by the original publisher of the respective API:

function updateAPIDocs (bytes16 api,
                        string memory docs) public;

[oberstet]

Q: In addition to API schema, terms and docs do we need an API meta(machine readable, but different from the contents ofschema`)?

[oberstet]

The relation between APIs and services (implementing said APIs), and between an API registry/catalog and a service registry - in general - is such:

source of diagram: https://wso2.com/blogs/thesource/2014/07/api-registry-and-service-registry/

For XBR

• the API registry/catalog is living on-chain as described above
• the service registry also lives on-chain - essentially every data market maintains its own service registry (again, see #38)

[oberstet]

Terminology:

• Interface ("API"): abstract but binding contract between two software components - in XBR, interfaces are always WAMP interfaces (a collection of PubSub topics and its event payloads, and RPC procedures and its call arguments, return and error payloads)
• API Catalog: global on-chain instance (singleton) of published APIs
• Service Registry: in XBR, each data market is a service registry
• Service: in XBR, always a XBR seller delegate which is a WAMP component that implements one or more interfaces (in above sense)
• Service Offer/Consent: in XBR, a seller may announce that it provides a service in a market which implements one or more interfaces

[oberstet]

XBR API schema definition: this needs some design around the following constraints (which are already clear at this point):

• the URIs of WAMP topics, procedures and errors must be defined
• the payload of WAMP events and WAMP call arguments/results/errors should be defined in FlatBuffers schema

here is a first sketch of how that may look like:

https://github.com/crossbario/xbr-protocol/blob/ccc0cc08e6137105adf776a7c3678589a8378654/schema/example1.fbs

[oberstet]

so with above design, we would have the following top-level entities:

• XBRCatalog: this issue
• XBRMarket: see #48
• XBRDomain: see #54

[oberstet]

XBRNetwork.register(eula, profile)

XBRNetwork.createMarket(terms, meta) ->  market adr

        market terms content: zip file with documents

        market terms ipfs adr (from content)

        market meta content:

            market name
            market title
            market description
            market tags
            market icon
            market homepage
            market created timestamp + blocknumber
            transaction plane wamp url + realm & market maker adr
            data plane wamp url + realm

        market meta ipfs adr (from content)

    XBRMarket.join(actor types, meta, consent)

    XBRMarket.openBuyerChannel(recipient, delegate, amount)

    XBRMarket.openSellerChannel(recipient, delegate, amount)

XBRNetwork.createCatalog(terms, meta) -> catalog adr

    XBRCatalog.publishAPI(api id, meta)

    XBRCatalog.publishService(service id, meta)

[oberstet]

landed via #90