Developing the APIs

Protocol APIs

Following are the APIs to be developed by BAP and BPP:


BAP should consume the following on_action APIs and trigger action APIs.

  • on_search API

  • on_select API

  • on_init API

  • on_confirm

  • on_status

  • on_update

  • on_rating

  • on_support


BPP should consume the following action APIs and trigger on_action APIs.

  • search API

  • select API

  • init API

  • confirm

  • status

  • update

  • rating

  • support

Steps to create a Request:

  1. All the action and on_action APIs have context and message objects. Refer to this link to understand the list of properties in the context object. Message object varies based on the API, refer Reference Implementation Guides for examples. Below is the sample API request with context and message objects.

  "context": {
    "domain": "onest:learning-experiences",
    "transaction_id": "a9aaecca-10b7-4d19-b640-b047a7c62196",
    "message_id": "$bb579fb8-cb82-4824-be12-fcbc405b6608",
    "action": "search",
    "timestamp": "2022-12-15T05:23:03.443Z",
    "version": "1.1.0",
    "bap_uri": "",
    "bap_id": "",
    "ttl": "PT10M"
  "message": {
    "intent": {
      "item": {
        "descriptor": {
          "name": "english"
  1. Participant should sign the payload and send to gateway. Steps to sign the request payload and verify when a payload received.

  2. Error codes implementation by BAP and BPP.

  3. Only search API goes through gateway, rest all APIs are between BAP and BPP. Example: BAP sends search API to gateway, and it will broadcast to all available providers in that domain. Next, BPP will make on_search API directly to BAP.

Note: Protocol Server is a utility, which helps the participants to quickly develop the protocol APIs. It will help in signing and verification of payload signature, schema validation, sending and receiving requests to Gateway and Participants.

Sample code for implementing signature and verification.

Registry Lookup API

The registry lookup API can be used to get the details of all the participants in the registry. In request body, type can be BG,BAP, BPP

curl --location '' \
--header 'Content-Type: application/json' \
--data '{
    "country": "IND",

Gateway URL

Last updated