Skip to content

API examples (JSON Support)

Jump to bottom
sknirmalkar89 edited this page Nov 23, 2020 · 6 revisions

From release 1.1.0 only, json payloads were supported.

Table of Contents

Create

This creates a new record in the registry.

POST - /add,  
Content Type - application/json

Request Body

{
  "id": "open-saber.registry.create",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
    "Teacher": {
      "signatures": {
        "@type": "sc:GraphSignature2012",
        "signatureFor": "http://localhost:8080/serialNum",
        "creator": "https://example.com/i/pat/keys/5",
        "created": "2017-09-23T20:21:34Z",
        "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
        "signatureValue": "eyiOiJKJ0eXA...OEjgFWFXk"
      },
      "serialNum": 6,
      "teacherCode": "12234",
      "nationalIdentifier": "1234567890123456",
      "teacherName": "Marvin Pande",
      "gender": "GenderTypeCode-MALE",
      "birthDate": "1990-12-06",
      "socialCategory": "SocialCategoryTypeCode-GENERAL",
      "highestAcademicQualification": "AcademicQualificationTypeCode-PHD",
      "highestTeacherQualification": "TeacherQualificationTypeCode-MED",
      "yearOfJoiningService": "2014",
      "teachingRole": {
        "@type": "TeachingRole",
        "teacherType": "TeacherTypeCode-HEAD",
        "appointmentType": "TeacherAppointmentTypeCode-REGULAR",
        "classesTaught": "ClassTypeCode-SECONDARYANDHIGHERSECONDARY",
        "appointedForSubjects": "SubjectCode-ENGLISH",
        "mainSubjectsTaught": [
          "SubjectCode-SOCIALSTUDIES",
          "SubjectCode-ENGLISH"
        ],
        "appointmentYear": "2015"
      },
      "inServiceTeacherTrainingFromBRC": {
        "@type": "InServiceTeacherTrainingFromBlockResourceCentre",
        "daysOfInServiceTeacherTraining": "10"
      },
      "inServiceTeacherTrainingFromCRC": {
        "@type": "InServiceTeacherTrainingFromClusterResourceCentre",
        "daysOfInServiceTeacherTraining": "2"
      },
      "inServiceTeacherTrainingFromDIET": {
        "@type": "InServiceTeacherTrainingFromDIET",
        "daysOfInServiceTeacherTraining": "5.5"
      },
      "inServiceTeacherTrainingFromOthers": {
        "@type": "InServiceTeacherTrainingFromOthers",
        "daysOfInServiceTeacherTraining": "3.5"
      },
      "nonTeachingAssignmentsForAcademicCalendar": {
        "@type": "NonTeachingAssignmentsForAcademicCalendar",
        "daysOfNonTeachingAssignments": "6"
      },
      "basicProficiencyLevel": [
        {
          "@type": "BasicProficiencyLevel",
          "proficiencySubject": "SubjectCode-MATH",
          "proficiencyAcademicQualification": "AcademicQualificationTypeCode-PHD"
        },
        {
          "@type": "BasicProficiencyLevel",
          "proficiencySubject": "SubjectCode-ENGLISH",
          "proficiencyAcademicQualification": "AcademicQualificationTypeCode-HIGHERSECONDARY"
        },
        {
          "@type": "BasicProficiencyLevel",
          "proficiencySubject": "SubjectCode-SOCIALSTUDIES",
          "proficiencyAcademicQualification": "AcademicQualificationTypeCode-SECONDARY"
        }
      ],
      "disabilityType": "DisabilityCode-NA",
      "trainedForChildrenSpecialNeeds": "YesNoCode-YES",
      "trainedinUseOfComputer": "YesNoCode-YES"
    }
  }
}

Response

{
    "id": "open-saber.registry.create",
    "ver": "1.0",
    "ets": 1539344132210,
    "params": {
        "resmsgid": "",
        "msgid": "96345148-464e-452a-8541-fd9a0d5c9243",
        "err": "",
        "status": "SUCCESSFUL",
        "errmsg": ""
    },
    "responseCode": "OK",
    "result": {
        "Teacher": {
            "@id":"32f440cc-13a7-4b5e-915c-4272586a3572"
         }
    }
}

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,  
Content Type - application/json

Request Body

{
  "id": "open-saber.registry.update",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
    "Teacher": {
      "@id": "32f440cc-13a7-4b5e-915c-4272586a3572",
      "signatures": {
        "@type": "sc:GraphSignature2012",
        "signatureFor": "http://localhost:8080/serialNum",
        "created": "2017-09-23T20:21:34Z",
        "creator": "https://example.com/i/pat/keys/5",
        "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
        "signatureValue": "eyiOiJKJ0eXA...OEjgFWFXkUpdated"
      }
    }
  }
}
OR for nested record-
{
  "id": "open-saber.registry.update",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
    "TeachingRole": {
      "@id": "436360fd-6f0f-44bd-9b95-bd753ed98812",
      "signatures": {
        "@type": "sc:GraphSignature2012",
        "signatureFor": "http://localhost:8080/appointmentType",
        "created": "2017-09-23T20:21:34Z",
        "creator": "https://example.com/i/pat/keys/5",
        "nonce": "2bbgh3dgjg2302d-d2b3gi423d42",
        "signatureValue": "eyiOiJKJ0eXA...OEjgFWFXkUpdateddd"
      }
    }
  }
}

Response

{
    "id": "open-saber.registry.update",
    "ver": "1.0",
    "ets": 1539614296559,
    "params": {
        "resmsgid": "",
        "msgid": "89ef5506-83f0-4cc5-9025-e352bc236dba",
        "err": "",
        "status": "SUCCESSFUL",
        "errmsg": ""
    },
    "responseCode": "OK"
}

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. Optionally, you could add a view-template id (static) or view-template json (dynamic).

POST - /read,  
Accept - application/json or application/ld+json 
Default Accept - application/json

Request Body

{
  "id": "open-saber.registry.read",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
      "Teacher":{
        "@id": "9c7a6bf3-d39a-4016-a635-74cb4aa3cb7c",
        "includeSignatures": true
      }
  }
}

Response

{
    "id": "open-saber.registry.read",
    "ver": "1.0",
    "ets": 1539691954358,
    "params": {
        "resmsgid": "",
        "msgid": "acdf5edd-5429-4028-a19e-61c58d5f1f1e",
        "err": "",
        "status": "SUCCESSFUL",
        "errmsg": ""
    },
    "responseCode": "OK",
    "result": [
        {
            "Teacher": {
                "@id": "a09f00c0-6379-48a6-80d8-37d8c03906e8",
                "basicProficiencyLevel": [
                    {
                        "@id": "90ca11ad-95f8-4f09-aa4e-1c0676d24543",
                        "proficiencyAcademicQualification": "AcademicQualificationTypeCode-HIGHERSECONDARY",
                        "proficiencySubject": "SubjectCode-ENGLISH"
                    },
                    {
                        "@id": "46c82782-3713-42b0-b1cb-095a24538dd5",
                        "proficiencyAcademicQualification": "AcademicQualificationTypeCode-SECONDARY",
                        "proficiencySubject": "SubjectCode-SOCIALSTUDIES"
                    },
                    {
                        "@id": "e0fc24af-abf9-4f3b-9575-925045537ae0",
                        "proficiencyAcademicQualification": "AcademicQualificationTypeCode-PHD",
                        "proficiencySubject": "SubjectCode-MATH"
                    }
                ],
                "birthDate": "1990-12-06",
                "disabilityType": "DisabilityCode-NA",
                "gender": "GenderTypeCode-MALE",
                "highestAcademicQualification": "AcademicQualificationTypeCode-PHD",
                "highestTeacherQualification": "TeacherQualificationTypeCode-MED",
                "inServiceTeacherTrainingFromBRC": {
                    "@id": "dc22af6b-f8bf-440b-998d-dd5e5d7c57c1",
                    "daysOfInServiceTeacherTraining": "10"
                },
                "inServiceTeacherTrainingFromCRC": {
                    "@id": "fc580075-bd8c-4c75-b9dd-196a001a620c",
                    "daysOfInServiceTeacherTraining": "2"
                },
                "inServiceTeacherTrainingFromDIET": {
                    "@id": "e1eb790e-6e6b-48cc-b8df-9d0b91245f38",
                    "daysOfInServiceTeacherTraining": "5.5"
                },
                "inServiceTeacherTrainingFromOthers": {
                    "@id": "bef5e773-9f6b-46d3-88d1-9519b2c32822",
                    "daysOfInServiceTeacherTraining": "3.5"
                },
                "nationalIdentifier": "1234567890123456",
                "nonTeachingAssignmentsForAcademicCalendar": {
                    "@id": "f284746d-6ed3-49fc-bbeb-1644d9b759d4",
                    "daysOfNonTeachingAssignments": "6"
                },
                "serialNum": 6,
                "socialCategory": "SocialCategoryTypeCode-GENERAL",
                "teacherCode": "12234",
                "teacherName": "Marvin Pande",
                "teachingRole": {
                    "@id": "70add9f0-7dee-41d3-9f67-2d3e1498fedd",
                    "appointedForSubjects": "SubjectCode-ENGLISH",
                    "appointmentType": "TeacherAppointmentTypeCode-REGULAR",
                    "appointmentYear": "2015",
                    "classesTaught": "ClassTypeCode-SECONDARYANDHIGHERSECONDARY",
                    "mainSubjectsTaught": [
                        "teacher:SubjectCode-ENGLISH",
                        "teacher:SubjectCode-SOCIALSTUDIES"
                    ],
                    "teacherType": "TeacherTypeCode-HEAD"
                },
                "trainedForChildrenSpecialNeeds": "YesNoCode-YES",
                "trainedinUseOfComputer": "YesNoCode-YES",
                "yearOfJoiningService": "2014"
            }
        }
    ]
}

Example with static view template

"request": {
    "Teacher": {
        "osid": "1-80953674-4b2a-411c-b3c6-ccccf67cac74"
    },
    "viewTemplateId": "6245495a-4525-11ea-b77f-2e728ce88125.json"
}

Example with dynamic view template

"request": {
    "Teacher": {
        "osid": "1-80953674-4b2a-411c-b3c6-ccccf67cac74"
    },
    "viewTemplate": {
        "fields": [
            {
                "name": "name",
                "title": "FullName"
            },
            {
                "name": "gender",
                "display": true
            }
        ]
    }
}

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": "open-saber.registry.delete",
  "ver": "1.0",
  "ets": "",
  "params": {
    "resmsgid": "",
    "msgid": "",
    "err": "",
    "status": "successful",
    "errmsg": ""
  },
  "responseCode": "OK"
}

Search

Search can also take in a view-template input, like the Read API with a difference - Private fields that are encrypted and stored will not be seen decrypted in the search results.

Generic search payload

{
  "id": "open-saber.registry.search",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
    "entityType": [root1....rootN],
    "filters": {
      "field 1": {"operator1":"value1"},
      "field 2": {"operator2":"value2"}  	
    }
   "limit": N, 
   "offset" : n
  }
}

where

root: the subject being searched for
field: property to filter
operator: one of above string or numeric operator as given below
limit: the number of search results that could be returned. Default and max is 100 (can be changed in application configuration)
offset: the particular page number of the search result 

Note: The fields are 'and'ed together in search. The search result would satisfy all the field conditions.

Operators

String operators supported

  • "contains" → String match, contains
  • "startsWith" → String match, starts with
  • "endsWith" → String match, ends with
  • "notContains" → negation of contains
  • "notStartsWith" → negation of startsWith
  • "notEndsWith" → negation of endsWith
  • “queryString” → free text search (not available Native search)

Other operators supported

  • "eq" or "=" → equal to
  • "neq" or "!=" → not equals
  • "gte" or ">=" → Greater than or equals
  • "gt" or ">" → Greater than
  • "lte" or "<=" →  Less than or equals
  • "lt" or "<" →  Less than
  • "between [low, high]" or "range" [low, high] → where low <= result < high
  • "or [val 1, val 2, val 3,..., val n] " → values belongs to one of the given

Examples:

Find a teacher with serialNumber equal to 1

{
  "id": "open-saber.registry.search",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
  
   "entityType": ["Teacher"],
    "filters": {
      "serialNum": {"eq":1} 	
    }
  }
}

Find all Teachers with property serialNum in range [1-2]

{
  "id": "open-saber.registry.search",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
   "entityType": ["Teacher"],
    "filters": {
      "serialNum": {"range":[1,2]} 	
    }
  }
}

Find all Teachers with property teacherName as "Mahir" or "Jash"

{
  "id": "open-saber.registry.search",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  }
  "request": {
 "entityType": ["Teacher"],
    "filters": {
      "teacherName": {"or":["Mahir","Jash"]} 	
    }
  }
}

Find 10 Teacher records

{
  "id": "open-saber.registry.search",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
   "entityType": ["Teacher"],
    "filters": {
      
    },
    "limit":10,
    "offset":0
  }
}

Find free text for Marvin Pande

{
  "id": "open-saber.registry.search",
  "ver": "1.0",
  "ets": "11234",
  "params": {
    "did": "",
    "key": "",
    "msgid": ""
  },
  "request": {
   "entityType": ["Teacher"],
    "queries": "Marvin Pande"
  }
}
Clone this wiki locally