How to Integrate

Introduction to Integration

Integrating UTU into your app enables users to share their feedback and endorsements with other users in your and other apps. For this purpose, UTU provides an easy to use Web SDK and an API. This chapter describes all the required steps.

Using the UTU Web SDK

UTU provides SDKs to easily integrate the UTU Trust Engine into client apps. This includes showing relevant recommendations and providing user feedback after they used a service or bought a product or asset. Currently, the SDK supports any Javascript-enabled web app, including React, Vue.js, Angular (all versions), php or vanilla html. Support for mobile apps (Android, iOS) will be added soon.

SDK Initialization and Wallet Authentication

As described above, UTU takes feedback from users and shows personalized feedback about services and products. This means that the UTU Trust Engine deals with user-specific and, in some cases, sensitive data. In the future, this will be handled by zero-knowledge methods. For now, this information is stored in UTU’s backend. Authentication for the same is based on the user signing-in with their web3 wallet and works as follows:

  1. Connect the Wallet: The user initiates the process by selecting to connect their web3 wallet within the application, as is usual in typical web3 d-apps. See our example apps for how this can be done, e.g. using web3modal from a “Connect to Wallet” button in the React example app.

  2. Sign a Message: An authentication message is generated by the UTU SDK using the SDK’s addressSignatureVerification() function. The user signs this message using their private key within the web3 wallet. This step can be triggered automatically after the wallet is connected, or by the user clicking a button. See our example apps for how this can be done, e.g. the “Connect to UTU” button in the React example app.

  3. Verify the Signature: After the user signs the message in the previous step, the SDK automatically sends it to the UTU backend, which verifies the signature against the user’s public address. This ensures that the user is the owner of the web3 wallet. The resulting AuthData-type response is returned asynchronously from addressSignatureVerification(). See e.g. the addressSignatureVerification() call in the React example app.

  4. Token Generation: Upon successful verification, the returned AuthData contains a user-specific and time-limited token (JWT) generated by the UTU API. This token authorizes the user’s access to the UTU Trust Engine for a limited time. In the future, the SDK will automatically store this. For now, the token needs to be passed back to the SDK by dispatching a utuIdentityDataReady event, with the AuthData set as the value of a detail property. See e.g. dispatching an “utuIdentityDataReady” event in the React example app.

Informing the UTU Trust Engine about Entities

To show relevant feedback about an entity to a user from their own network, the UTU Trust Engine needs to be informed about relationships between users, and about the entities about which feedback is given. This could be tokens, other smart contracts or other entities such as urls, as is done e.g. in the UTU Browser Extention.

While relationships are automatically added for users who connect social media platforms – via the Social Media Connectore – or who have on-chain transactions – via the blockchain scanner –, entities need to be added manually. This is done by calling the POST /entities service of the UTU API. In the future, we will provide a function in the UTU SDKs which will make this process easier. For now, you can refer to our example apps how this can be done, e.g. in the React example app.

There are certain already existing target types in the shared global database, such as “DeFiProtocl” or “Address”; we encourage integrators to enquire with us what best to use here.

Getting Recommendations and Providing Feedback

Having been informed about entities and relationships between them, the UTU Trust Engine can serve social recommendations or other feedback, provided that users give that feedback. For this, the UTU API provides the GET /ranking, POST /feedback and GET /feedbackSummary services. However, UTU’s frontend SDKs also provide ready-made UI components which can be easily added to the client app and which take care of the invocation of these services automatically (see next section “SDK Usage”). Generally, the user journey through a client platform app, including showing UTU recommendations, feedback details, and providing feedback, looks similar to this sequence:

@startuml !include ../utu-theme.puml actor User participant "Client platform app" As app participant "Client platform backend" As backend participant "UTU API" as API #FEE534 group Ranking and Feedback group Show offers User -> app ++: Select service/product entities app -> API++ : GET /ranking (entities) return Entities with personalised\nfeedback summary return Show entities with personalised\n feedback summary to choose from end group User interacts with offers User -> app++: Show detailed feedback app -> API++: GET /feedbackSummary return Feedback detail summary return Show feedback details end group User chooses an offer User -> app ++: Choose entity app -> backend ++: Create transaction for\n user and entity return return end group Execute transaction User -> User: Consume service/product end group User endorses and/or gives feedback User -> app ++: Endorse app -> UTT ++: Call endorse() function UTT -> UTT : invoke oracle and reward return deactivate app User -> app ++: Give feedback app -> API ++: POST /feedback return deactivate app end end @enduml

UTU API Sequence Ranking and Feedback

SDK Usage

Typically, an app will have a page showing a selection of services or products to a user. This could be the app’s start page, or a page with search or filter results. We call this an “offer page”. On this page, UTU’s SDK can be used to show feedback summary, where available, for each offered service or product. We also call feedback summary about an entity a “recommendation”.

Just import the UTU SDK library, wrap the offers list in an <x-utu-root/> element (this triggers loading of relevant recommendations from UTU backend) and put an <x-utu-recommendation/> element where UTU’s recommendation should be shown.

The SDK can also show a button to open a popup view with feedback details, using the <x-utu-feedback-details-popup/> element, and for asking feedback from the user after a transaction with the <x-utu-feedback-form-popup/> element. Both are also available as non-popups, to be shown inline e.g. in a service/product detail page and a post-transaction “thank you” or similar page. Detailed information about all UTU web components can be found in the Web Components Reference section.

Here is a simple example, showing the use of these elements in an “Offers” function, which is a minimal component to show a list of offers, in a React app:

export default function Offers(props: any) {
  let offers = props.offers;
  let _window: any = window;
  let provider = _window.ethereum;
  let walletAddress = provider.selectedAddress;

  // @ts-ignore
  return (
    <div className="offers">
      <ul>
        {
          offers.map((offer: any) =>
            <li className="offer" key={offer.id}>
              <div style={{ fontWeight: 'bold' }}>{offer.name}</div>
              <x-utu-root
                source-uuid={walletAddress}
                target-type="provider"
                target-uuids={getId(offer.id)}>
                <x-utu-recommendation
                  target-uuid={getId(offer.id)}
                  style={{ marginTop: "-20px" }} />
              </x-utu-root>
              <br />
              <x-utu-feedback-details-popup
                target-uuid={getId(offer.id)}
                source-uuid={walletAddress}
              />
              <x-utu-feedback-form-popup
                source-uuid={walletAddress}
                target-uuid={getId(offer.id)}
                transaction-id={5} />
            </li>
          )
        }
      </ul>
    </div>
  );
}

Example Apps

The full React and other example d-apps can be viewed and cloned from the following repositories:

Web Components Reference

This section describes all the web components provided by the UTU Web SDK. The components are designed to be used in any Javascript-enabled web app. They’re provided roughly in the order of a typical integration workflow.

x-utu-root

Description

The x-utu-root component serves as the main container for the recommendation system. It fetches ranking data from the API and dispatches a “loaded” event with the ranking data.

Attributes

  • source-uuid: (Required) Specifies the source UUID for the ranking.

  • target-type: (Required) Specifies the target type for the ranking. There are certain already existing target types, such as “DeFiProtocol” or “Address”; we encourage integrators to enquire with us what best to use here.

  • target-uuids: (Optional) Specifies a space-separated list of target UUIDs, if a predefined list of entities is to be ranked. If this is not provided, the ranking will include all entities of the given type.

Example Usage
<x-utu-root source-uuid="0x123..." target-type="DeFiProtocol" target-uuids="0x456...">
    <!-- Offered entities with x-utu-recommendation components go here -->
</x-utu-root>
Events

  • loaded: Dispatched when the ranking data is loaded. The event detail contains the data property with the ranking items.

x-utu-recommendation

Description

The x-utu-recommendation component displays a recommendation based on the ranking data provided by the x-utu-root component. It listens to the “loaded” event from the x-utu-root component to get the ranking data and renders the recommendation accordingly.

Attributes

  • target-uuid: (Required) Specifies the target UUID for the recommendation.

Example Usage
<!-- Inside a x-utu-root component -->
<x-utu-recommendation target-uuid="0x456..." />

x-utu-feedback-details

Description

The x-utu-feedback-details component displays detailed feedback information, including videos, star ratings, badges, endorsements, and text reviews. It provides both mobile and desktop views. This is for displaying feedback details inline in other components. If a popup is preferred, use the x-utu-feedback-details-popup component instead.

Attributes

  • source-uuid: (Required) Specifies the source UUID for the feedback details.

  • target-uuid: (Required) Specifies the target UUID for the feedback details.

Example Usage
<x-utu-feedback-details source-uuid="0x123..." target-uuid="0x456..." />

x-utu-feedback-details-popup

Description

The x-utu-feedback-details-popup component provides a button to display detailed feedback information in a popup window. It includes videos, star ratings, badges, endorsements, and text reviews. This is for displaying feedback details inline in other components. If a popup is preferred, use the x-utu-feedback-details-popup component instead.

Attributes

  • source-uuid: (Required) Specifies the source UUID for the feedback details. Example: “0x123…”

  • target-uuid: (Required) Specifies the target UUID for the feedback details. Example: “0x456…”

  • btn-color: (Optional) Specifies the button color.

Example Usage
<x-utu-feedback-details-popup source-uuid="0x123..." target-uuid="0x456..." btn-color="#FF5733" />

utu-feedback-form

Description

The utu-feedback-form component provides a form to collect feedback from users. It includes sections for recording videos, star ratings, badges, text input, and endorsements.

Attributes

  • source-uuid: (Required) Specifies the source UUID.

  • target-uuid: (Required) Specifies the target UUID.

  • transaction-id: (Optional) Specifies the transaction ID.

Example Usage
<utu-feedback-form api-url="https://api.example.com" source-uuid="0x123..." target-uuid="0x456..." />
utu-feedback-form-popup
Description

The utu-feedback-form-popup component provides a popup form to collect feedback from users. It includes sections for recording videos, star ratings, badges, text input, and endorsements.

Attributes

  • source-uuid: (Required) Specifies the source UUID.

  • target-uuid: (Required) Specifies the target UUID.

  • transaction-id: (Optional) Specifies the transaction ID.

  • btn-color: (Optional) Specifies the button color.

Example Usage
<utu-feedback-form-popup source-uuid="0x123..." target-uuid="0x456..." />

x-utu-header

Description

The utu-header component provides a simple header “Feedback From Your Network”.

Example Usage
<utu-header />

x-utt-balance

Description

The utt-balance component displays the balance of UTT (a specific token) in the user’s wallet. It fetches the balance using the connected wallet. A loading indicator is shown while the balance is being fetched.

Example Usage
<utt-balance />

x-utu-wallet-connect

Description

The utu-wallet-connect component provides a button to connect a user’s wallet. It’s designed to interact with Ethereum wallets and displays a prompt to see UTU trust signals from the user’s network. This is mostly useful for non-web3 apps that don’t provide their own wallet connection but still want to use UTU’s trust signals.

Example Usage
<utu-wallet-connect />

x-utu-disconnect-wallet

Description

The utu-disconnect-wallet component provides a button to disconnect a user’s wallet. It’s designed to interact with Ethereum wallets and allows the user to disconnect their wallet from the application. This is mostly useful for non-web3 apps that don’t provide their own wallet connection but still want to use UTU’s trust signals.

Example Usage
<utu-disconnect-wallet />

Using the UTU API

The UTU API is a RESTful API which can be used separately or in addition to the UTU SDKs if more fine-grained control is needed.

For a summarised list of the API’s main concepts (types), see Main Concepts in the Introduction.

OpenAPI Specification

Download the OpenAPI specification for the UTU API, which can be used to generate client libraries for various languages.

Trust API Specification Reference

ranking

GET /ranking

Retrieves entities of given type with feedback on each, if existing. Entities are sorted by their overall feedback status. Note that feedback might be positive or negative, i.e. it might be approving (i.e. a ranking), neutral or disapproving of the entity.

For a client, entity type and a list of entity-identifying criteria, returns a sorted array of entity info objects. Optionally, a context object may be given which provides entity type-specific information relevant to the concerned request, such as the origin and destination of a taxi ride when looking for recommendations for taxi drivers.

Query Parameters:

  • sourceCriteria (object) – An object with properties identifying the source entity to get recommendations for. Contained properties have to match identifying property names and values which were given in previous postEntity calls’ ids property such that exactly one client is identified by them (if more than one matches, a 400 error is returned). (Required)

  • targetType (string) – Type of the entities to be recommended. (Required)

  • targetCriterias (array) – An optional array of objects with properties identifying the entities to sort; if omitted, all entities of the given type are considered.

Example request:

GET /ranking?sourceCriteria=OrderedDict%28%5B%28%27type%27%2C+%27string%27%29%2C+%28%27ids%27%2C+OrderedDict%28%5B%28%27uuid%27%2C+%27string%27%29%5D%29%29%5D%29&targetType=string HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    A sorted array of entity info objects, each containing 1. entity - an object containing identifying properties of the entity as they have been given in the postEntity which added it. 2. isFavourite - flag indicating whether this entity is a direct favourite of the client. 3. socialFavourite - if the entity is not a direct favourite, this contains, if existing, the “best” “social favourite”, which is an array of objects containing the name of the target node (usually an entity representing a person) and its relationship “type” (e.g. “Facebook”). The first element is a direct relationship of the client, and the last element recommends the entity (the client and entity themselves are omitted).

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": [
        {
            "entity": {
                "name": "MakerDAO",
                "uuid": "e541df40-74b6-478e-a7da-7a9e52778700",
                "image": "https://etherscan.io/images/defi/maker.svg?v20.8.3",
                "type": "DeFiProtocol",
                "properties": {
                    "category": "Lending",
                    "description": "Collateralized loans on Maker",
                    "url": "https://makerdao.com"
                }
            },
            "relationshipPaths": [
                [
                    {
                        "targetEntity": {
                            "name": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
                            "image": "https://via.placeholder.com/150/FFFF00/000000/?text=0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
                            "type": "Address",
                            "properties": {}
                        },
                        "relationship": {
                            "inverse": false,
                            "type": "interaction",
                            "properties": {
                                "txId": "0x6241e81499a6cefb119c80981b49613585466f4c4ddf4275a0588fb5a979df0a",
                                "timestamp": "2020-10-16T06:11:44Z",
                                "action": "interaction"
                            }
                        }
                    },
                    {
                        "targetEntity": {
                            "name": "MakerDAO",
                            "image": "https://etherscan.io/images/defi/maker.svg?v20.8.3",
                            "type": "DeFiProtocol",
                            "properties": {
                                "category": "Lending",
                                "description": "Collateralized loans on Maker",
                                "url": "https://makerdao.com"
                            }
                        },
                        "relationship": {
                            "inverse": false,
                            "type": "interaction",
                            "properties": {
                                "txId": "0xbb14e0037302c1ed8b3e45cbe193899548f99dd6b35450ee6684737c970c9cf1",
                                "timestamp": "2020-11-13T16:15:42Z",
                                "action": "Transfer"
                            }
                        }
                    }
                ]
            ],
            "summaryText": "You and 1 in your network used MakerDAO",
            "summaryImages": [
                "https://via.placeholder.com/150/FFFF00/000000/?text=0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D"
            ]
        },
        {
            "entity": {
                "name": "Bancor Network",
                "uuid": "16647fb7-9e37-4485-903d-2e186ea82d4a",
                "image": "https://etherscan.io/images/defi/bancor.png?v20.8.3",
                "type": "DeFiProtocol",
                "properties": {
                    "category": "DEX",
                    "description": "Automated liquidity protocol",
                    "url": "https://bancor.network"
                }
            },
            "relationshipPaths": [],
            "summaryText": null,
            "summaryImages": []
        }
    ]
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}

feedback

POST /feedback

Add feedbacks for an entity

Associate a list of feedbacks to an Entity

Example request:

POST /feedback HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "sourceCriteria": {
        "type": "user",
        "uuid": "6061f3e1-e38d-4ba7-ab9c-c73d4af98dff"
    },
    "targetCriteria": {
        "type": "service",
        "ids": [
            {
                "name": "Trust Engine"
            }
        ]
    },
    "transactionId": "16647fb7-9e37-4485-903d-2e186ea82d4a",
    "items": {
        "badges": {
            "punctuality": "positive",
            "car-size": "negative",
            "cleanliness": "positive"
        },
        "stars": 4,
        "video": "http://youtube.com/123123",
        "review": "Great experience!"
    }
}
Status Codes:

  • 200 OK –

    Relation updated

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • 201 Created –

    Relation created

    Example response:

    HTTP/1.1 201 Created
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}

GET /feedbackSummary

Get aggregated feedback for a target

Query Parameters:

  • targetCriteria (object) – An object with properties identifying the target entity to get feedback for. Contained properties have to match identifying property names and values which were given in previous postEntity calls’ ids property such that exactly one client is identified by them (if more than one matches, a 400 error is returned). (Required)

  • sourceCriteria (object) – An object with properties identifying the source entity to get recommendations from. Contained properties have to match identifying property names and values which were given in previous postEntity calls’ ids property such that exactly one client is identified by them (if more than one matches, a 400 error is returned). (Required)

  • limit (integer) – Limit the number of feedback to aggregate

Example request:

GET /feedbackSummary?targetCriteria=OrderedDict%28%5B%28%27type%27%2C+%27string%27%29%2C+%28%27ids%27%2C+OrderedDict%28%5B%28%27uuid%27%2C+%27string%27%29%5D%29%29%5D%29&sourceCriteria=OrderedDict%28%5B%28%27type%27%2C+%27string%27%29%2C+%28%27ids%27%2C+OrderedDict%28%5B%28%27uuid%27%2C+%27string%27%29%5D%29%29%5D%29 HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Feedback summary

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": {
        "target": {
            "name": "MakerDAO",
            "uuid": "e541df40-74b6-478e-a7da-7a9e52778700",
            "image": "https://etherscan.io/images/defi/maker.svg?v20.8.3",
            "type": "DeFiProtocol",
            "properties": {
                "category": "Lending",
                "description": "Collateralized loans on Maker",
                "url": "https://makerdao.com"
            }
        },
        "items": {
            "stars": {
                "count": 3,
                "sum": 14,
                "avg": 4,
                "666666667": null
            },
            "review": {
                "content": "Very nice usage experience, it is a bit expensive to get start, but worth it!",
                "date": 1616490049,
                "image": "https://robohash.org/mark?set=set5"
            },
            "video": {
                "date": 1616490049,
                "url": "https://www.youtube.com/embed/watch?v=U7DOa9pZtsk",
                "image": "https://robohash.org/alice?set=set5"
            },
            "badges": {
                "Punctuality": {
                    "negative": {
                        "count": 2,
                        "badge": {
                            "label": "late",
                            "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/images/timelines_negative.svg"
                        }
                    }
                },
                "Experience": {
                    "positive": {
                        "count": 2,
                        "badge": {
                            "label": "thumb up",
                            "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/images/experience_positive.svg"
                        }
                    }
                }
            },
            "endorsements": [
                {
                    "source": {
                        "name": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
                        "image": "https://via.placeholder.com/150/FFFF00/000000/?text=0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
                        "type": "Address",
                        "properties": {}
                    },
                    "endorsement": {
                        "value": 10,
                        "blockNumber": 5
                    }
                }
            ]
        }
    }
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}

interactions

GET /interactionSummary

Get (non-user-feedback) interactions for a target

Query Parameters:

  • targetCriteria (object) – An object with properties identifying the target entity to get feedback for. Contained properties have to match identifying property names and values which were given in previous postEntity calls’ ids property such that exactly one client is identified by them (if more than one matches, a 400 error is returned). (Required)

  • sourceCriteria (object) – An object with properties identifying the source entity to get recommendations from. Contained properties have to match identifying property names and values which were given in previous postEntity calls’ ids property such that exactly one client is identified by them (if more than one matches, a 400 error is returned). (Required)

Example request:

GET /interactionSummary?targetCriteria=OrderedDict%28%5B%28%27type%27%2C+%27string%27%29%2C+%28%27ids%27%2C+OrderedDict%28%5B%28%27uuid%27%2C+%27string%27%29%5D%29%29%5D%29&sourceCriteria=OrderedDict%28%5B%28%27type%27%2C+%27string%27%29%2C+%28%27ids%27%2C+OrderedDict%28%5B%28%27uuid%27%2C+%27string%27%29%5D%29%29%5D%29 HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    Interaction summary

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}

badges

GET /badges

Retrieves the list of available badge sets

Get a list of available badges sets available in the system

Example request:

GET /badges HTTP/1.1
Host: example.com
Status Codes:

  • 200 OK –

    BadgeSet list

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": [
        {
            "id": "Experience",
            "badges": [
                {
                    "qualifier": "positive",
                    "badge": {
                        "label": "thumb up",
                        "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/images/experience_positive.svg"
                    }
                },
                {
                    "qualifier": "negative",
                    "badge": {
                        "label": "thumb down",
                        "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/images/experience_negative.svg"
                    }
                }
            ]
        },
        {
            "id": "Punctuality",
            "badges": [
                {
                    "qualifier": "positive",
                    "badge": {
                        "label": "on time",
                        "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/images/timelines_positive.svg"
                    }
                },
                {
                    "qualifier": "negative",
                    "badge": {
                        "label": "late",
                        "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/images/timelines_negative.svg"
                    }
                }
            ]
        },
        {
            "id": "Quality",
            "badges": [
                {
                    "qualifier": "negative",
                    "badge": {
                        "label": "bad quality",
                        "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/images/quality_negative.svg"
                    }
                },
                {
                    "qualifier": "positive",
                    "badge": {
                        "label": "good quality",
                        "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/images/quality_positive.svg"
                    }
                }
            ]
        }
    ]
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}

POST /badges

Register a new badge

Register a new badge set

Example request:

POST /badges HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "id": "quality",
    "badges": [
        {
            "qualifier": "positive",
            "badge": {
                "image": "",
                "label": "On Time"
            }
        },
        {
            "qualifier": "negative",
            "badge": {
                "image": "",
                "label": "Late"
            }
        }
    ],
    "image": "https://utu-trust-sdk.s3.eu-central-1.amazonaws.com/v2/badge-sets/Quality.svg"
}
Status Codes:

  • 200 OK –

    BadgeSet updated

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • 201 Created –

    Relation created

    Example response:

    HTTP/1.1 201 Created
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}

entity

POST /entity

Adds an entity

Adds an entity, such as a client or service provider for a specific service, to the system. Identifying properties have to be given in the object value of the ids property. Each of these is assumed to identify an entity unambiguously. Therefore, if an entity already exists which matches any of the newly posted entity’s ids, they are merged. When merging, properties (within ids or other properties) of the newly sent entity overwrite those of the existing one. Even though this is a POST method, it is actually idempotent: multiple calls with the same parameters and body will have the same effect on the stored data as a single call.

Example request:

POST /entity HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Albert Einstein",
    "type": "physicist",
    "ids": {
        "uuid": "f1c61c45-e470-411b-a9d0-e650cfa89582",
        "phoneNumber": "+254700000000"
    },
    "image": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6f/Einstein-formal_portrait-35.jpg/186px-Einstein-formal_portrait-35.jpg"
}
Status Codes:

  • 200 OK –

    Entity updated

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • 201 Created –

    Entity created

    Example response:

    HTTP/1.1 201 Created
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}

relationship

POST /relationship

Adds a social relationship

Creates a unique relationship of given type and with given properties from the source node(s) identified by sourceCriteria to all target node identified by elements of targetCriteria.

Example request:

POST /relationship HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "name": "Albert Einstein",
    "type": "physicist",
    "ids": {
        "uuid": "f1c61c45-e470-411b-a9d0-e650cfa89582",
        "phoneNumber": "+254700000000"
    },
    "image": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/6f/Einstein-formal_portrait-35.jpg/186px-Einstein-formal_portrait-35.jpg"
}
Status Codes:

  • 200 OK –

    Relation updated

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • 201 Created –

    Relation created

    Example response:

    HTTP/1.1 201 Created
Content-Type: application/json

{
    "status": "success",
    "result": {}
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}

previousEndorsers

POST /previousEndorsersRequest

Retrieves the previous endorsers for the UTT oracle.

Retrieves the previous first- and second-degree endorsers for a new endorsement; this is used by the UTT oracle in order to reward them. This should really be a GET, but the used Chainlink oracle doesn’t support query params.

Example request:

POST /previousEndorsersRequest HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "sourceAddress": "0xa58a4f5c4Bb043d2CC1E170613B74e767c94189B",
    "targetAddress": "0xa58a4f5c4Bb043d2CC1E170613B74e767c94189B",
    "transactionId": "1234"
}
Status Codes:

  • 200 OK –

    Previous endorsers and their previous endorsers

    Example response:

    HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "result": {
        "firstLevelPreviousEndorsers": [
            "0xa58a4f5c4Bb043d2CC1E170613B74e767c94189B"
        ],
        "secondLevelPreviousEndorsers": [
            "0xa58a4f5c4Bb043d2CC1E170613B74e767c94189B"
        ]
    }
}

  • default –

    Any error

    Example response:

    HTTP/1.1 default -
Content-Type: application/json

{
    "status": "error",
    "errorCode": 1.0,
    "errorMessage": "string"
}