API Specifications


Overview

OpenSABER is a trusted data store interface for managing profile data of users irrespective of underlying storage. User has provision to create, update, read, delete and search for profile data based on defined role against him.


APIs

1. Create

This creates a new record in the registry.

POST - /create

Request Body

{
  "id": //identifier , e.g. "open-saber.registry.create",
  "ver": //verion no., "1.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "did": "", // device UUID from which API is called
    "key": "", // API key (dynamic)
    "msgid": "" // unique request message id, UUID
  },
  "request": {
    "@context": {
      "rdf": //expanded RDF, e.g. "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
      "rdfs": //rdf lists, e.g."http://www.w3.org/2000/01/rdf-schema#",
      "sample": //existing or custom vocabs, e.g. "http://example.com/voc/teacher/1.0.0/",
      ...
      "xsd": //schema namespace, e.g. "http://www.w3.org/2001/XMLSchema#",
      "@vocab": //existing or custom vocabs, e.g. "http://example.com/voc/teacher/1.0.0/"
     },
     "@graph": [
       {
         "@id": "sample:1205",
         "@type": "School",
         "academicCalendarYearEnd": {
           "@type": "xsd:gYear",
           "@value": "2018"
           ...
         },
         "address": {
           "@type": //edge of a node, e.g.,"IndianUrbanPostalAddress",
           // properties as key-val pair(s) where key is vocab-parameter 
           // and value is either literal or node , e.g.
          "city": "Gurgaon",
          "district": "Gurgaon",
          ...
          },
      ...
     },
     ...    
   ]
 }
}

Response

{
  "id": //identifier , e.g. "open-saber.registry.create",
  "ver": //version "1.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "resmsgid": "",
    "msgid": "",
    "err": "",
    "status": "successful",
    "errmsg": ""
  },
  "result": {              
    ...
  }
}

2. Update

This updates an existing record in the registry. Only properties of existing records can be updated via this API. The API will generate an error response if a valid identifier (@id) for the record or the nested records is not sent. These valid identifiers must be existing in database.

POST - /update

Request Body

{
  "id": //identifier , e.g. "open-saber.registry.update",
  "ver": //verion no., "1.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "did": "", // device UUID from which API is called
    "key": "", // API key (dynamic)
    "msgid": "" // unique request message id, UUID
    },
  "request": {
     "@context": {
      "rdf": //expanded RDF, e.g. "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
      "rdfs": //rdf lists, e.g."http://www.w3.org/2000/01/rdf-schema#",
      "sample": //existing or custom vocabs, e.g. "http://example.com/voc/teacher/1.0.0/",
        ...
      "xsd": //schema namespace, e.g. "http://www.w3.org/2001/XMLSchema#",
      "@vocab": //existing or custom vocabs, e.g. "http://example.com/voc/teacher/1.0.0/"
      },
      "@graph": {
       "@id": //label(identifier) of node, e.g., "sample:1234",
       "@type": //edge of a node, e.g.,"School",
       //properties that are being updated as key-val pair(s) where key is vocab-parameter 
       //and value is either literal or node. e.g:
       "schoolName": "DAV Public School",
       "district": "Gurgaon",
       "address": {
         "@id": //label(identifier) of node, e.g., "sample:677222f3-5f20-4ef3-ab43-56d0aa53e16f",
         "@type":"IndianUrbanPostalAddress",
         "district":"Mumbai"
         ...
       }
   }
}
}

Response

{
  "id": //identifier , e.g. "open-saber.registry.update",
  "ver": //version "1.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "resmsgid": "",
    "msgid": "",
    "err": "",
    "status": "successful",
    "errmsg": ""
  },
  "result": {              
    ...
  }
}

3. Add to an existing entity

This adds new objects to an existing record in the registry. The query parameters in the below spec specifies the id of the existing record to which this new object is added and property IRI through which this new object is connected to the existing record. The API will generate an error response if the identifier(id) is not present in the database.

POST - /add?id=<id>&prop=<propertyName>

Request Body

{
  "id": //identifier , e.g. "open-saber.registry.update",
  "ver": //verion no., "1.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "did": "", // device UUID from which API is called
    "key": "", // API key (dynamic)
    "msgid": "" // unique request message id, UUID
    },
  "request": {
     "@context": {
      "rdf": //expanded RDF, e.g. "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
      "rdfs": //rdf lists, e.g."http://www.w3.org/2000/01/rdf-schema#",
      "sample": //existing or custom vocabs, e.g. "http://example.com/voc/teacher/1.0.0/",
        ...
      "xsd": //schema namespace, e.g. "http://www.w3.org/2001/XMLSchema#",
      "@vocab": //existing or custom vocabs, e.g. "http://example.com/voc/teacher/1.0.0/"
      },
      "@graph": {
         "@type":"IndianUrbanPostalAddress",
         "district":"Mumbai"
         ...
   }
}
}

Response

{
  "id": //identifier , e.g. "open-saber.registry.add",
  "ver": //version "1.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "resmsgid": "",
    "msgid": "",
    "err": "",
    "status": "successful",
    "errmsg": ""
  },
  "result": {              
    ...
  }
}

4. Delete

This can be used to remove an entity from the database, the url path variable id specifies the entity id in the database. The API will generate an error response if the record or the entity does not exist.

DELETE - /delete/<id>

Response

{
  "id": //identifier , e.g. "open-saber.registry.delete",
  "ver": //version "1.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "resmsgid": "",
    "msgid": "",
    "err": "",
    "status": "successful",
    "errmsg": ""
  },
  "responseCode": "OK"
}

5. Read

This can be used to read an entity from the database, the url path variable id specifies the entity id in the database. The API will generate an error response if the record or the entity does not exist.

GET - /read/<id>

Response

{
  "id": //identifier , e.g. "open-saber.registry.read",
  "ver": //version "1.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "resmsgid": "",
    "msgid": "",
    "err": "",
    "status": "successful",
    "errmsg": ""
  },
  "responseCode": "OK",
  "result": {              
    ...
  }
}

6. Utility APIs

The following section lists down the utility APIs. You are free to choose and implement your for these, provided the response follows the same syntax.

6.1 Sign value

Use this API to sign a value for assertion later. You can either provide a single value or multiple of them in an array.

POST - /utils/sign

Request Body

{
  "id": "open-saber.utils.sign",
  "ver": "1.0.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "did": "", // device UUID from which API is called
    "key": "", // API key (dynamic)
    "msgid": "" // unique request message id, UUID
    },
  "request": {
    "value": "123456" // The value to be asserted.
}
}

Response

{
    "id": "open-saber.utils.sign",
    "ver": "1.0.0",
    "ets": 1538114862323,
    "params": {
        "resmsgid": "",
        "msgid": "76894dbb-8f16-44d6-b597-38595c18c141",
        "err": "",
        "status": "SUCCESSFUL",
        "errmsg": ""
    },
    "responseCode": "OK",
    "result": {
        "signatureValue": "K+SZ9hVBMOW9F3BA6WOSqe+FOQkdiwswJma1kUpFfC5PbtuHc32Fpu+BmUGQE94xTzxD5NX4XgbSz5FiqMSwVQ==",
        "keyId": 2,
        "version": "1.0.0"
    }
}
6.2 Sign entity

Use this API to sign an entity as a whole for assertion later. You can either provide a single entity or multiples of them in an array. This example shows a demonstration of array of entities for which signatures are being generated.

POST - /utils/sign

Request Body

{
  "id": "open-saber.utils.sign",
  "ver": "1.0.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "did": "", // device UUID from which API is called
    "key": "", // API key (dynamic)
    "msgid": "" // unique request message id, UUID
    },
  "request": {
    "entity":[  
            {"name": "Ram", "phone": "9901990101" }, 
            {"name": "John", "phone": "9901990102" }
    ]
}
}

Response

{
    "id": "open-saber.utils.sign",
    "ver": "1.0.0",
    "ets": 1538114862323,
    "params": {
        "resmsgid": "",
        "msgid": "76894dbb-8f16-44d6-b597-38595c18c141",
        "err": "",
        "status": "SUCCESSFUL",
        "errmsg": ""
    },
    "responseCode": "OK",
    "result": 
       [{ 
          "signatureValue": "YzlNSN++9wFO7hBEXLgM3wBqWnCOi/euSyrbFSigrQe+t+ZwB0VNLfWGWdjwY8v28JTmns7T5cEArOcXeuqDbQ==", 
          "keyId": 3, 
          "version": "1.0.0" 
        }, 
        { 
          "signatureValue": "oVYESGSI3C2Bc/gt+PjddJmmAPd7Eo+sPJ6FUzUw6FBlylAaShOYrpXqQbbsSLx3IkPwVYdfIgo5Y/ZatU8WyA==", 
          "keyId": 3, 
          "version": "1.0.0" 
        }]
    }
}
6.3 Verify value signature

Use this API to verify a value claim. You can either provide a single value claim or multiple value claims in an array. This example shows a demonstration of array of values that are being asserted.

POST - /utils/verify

Request Body

{
  "id": "open-saber.utils.verify",
  "ver": "1.0.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "did": "", // device UUID from which API is called
    "key": "", // API key (dynamic)
    "msgid": "" // unique request message id, UUID
    },
  "request": {
    "value": [{
            "claim": "Ramesh Kumar",
            "signatureValue": "Zof/AJu/ALQtD0OjuBFvs8dsZ/OfD08mC30ex5g1P1jV0IJYIHPscF0jGdGec/KkHmyvKkLU/hHiQ0czzr6Cvg==",
            "keyId": 2
        }, {
            "claim": "9901990101",
            "signatureValue": "tV0EHm0wKclS6v/gOhhaP51QcV39wUYPxYZCoA+4cGM2NicFGtjdMnV23HxZUR0CVxpVo91qBKeHbgpAD3/7pQ==",
            "keyId": 3
        }]
   }
}

Response

{
    "id": "open-saber.utils.verify",
    "ver": "1.0.0",
    "ets": 1538114862323,
    "params": {
        "resmsgid": "",
        "msgid": "76894dbb-8f16-44d6-b597-38595c18c141",
        "err": "",
        "status": "SUCCESSFUL",
        "errmsg": ""
    },
    "responseCode": "OK",
    "result": 
       [ true, true ]
    }
}
6.4 Verify entity signature

Use this API to verify a entity claim. You can either provide a single entity claim or multiple entity claims in an array. This example shows a demonstration of array of values that are being asserted.

POST - /utils/verify

Request Body

{
  "id": "open-saber.utils.verify",
  "ver": "1.0.0",
  "ets": //epoch timestamp in format "YYYY-MM-DDThh:mm:ssZ+/-nn.nn",
  "params": {
    "did": "", // device UUID from which API is called
    "key": "", // API key (dynamic)
    "msgid": "" // unique request message id, UUID
    },
  "request": {
    "entity": {
        "claim": {"name": "fruit", "color": "red"},
        "signatureValue": "qsAPIU0EN1+I+5LkjhPbxjQuWPKQIfkhCrP9mwchqdufhnnteOHOL0ZZfsbg8AgTVqTHNuvY7RYMfN2+d0wtvw==",
        "keyId": 2
    }
  }
}

Response

{
    "id": "open-saber.utils.verify",
    "ver": "1.0.0",
    "ets": 1538114862323,
    "params": {
        "resmsgid": "",
        "msgid": "76894dbb-8f16-44d6-b597-38595c18c141",
        "err": "",
        "status": "SUCCESSFUL",
        "errmsg": ""
    },
    "responseCode": "OK",
    "result": true
}