Using The APIs

The following guide walks you through the different Registry APIs using the example of a student-teacher registry.
Creating An Entity
We can create entities in the registry using the Create Entity API Endpoint.
To create a Teacher entity named Pranav Agate who teaches Math at UP Public School, we would make the following API call:
cURL
1
curl --location \
2
	--request 'POST' \
3
	--header 'content-type: application/json' \
4
	--data-raw '{
5
		"name": "Pranav Agate",
6
		"phoneNumber": "1234567890",
7
		"email": "[email protected]",
8
		"subject": "Math",
9
		"school": "UP Public School"
10
	}' \
11
	'http://localhost:8081/api/v1/Teacher/invite'
Copied!
HTTPie
1
echo '{
2
	"name": "Pranav Agate",
3
	"phoneNumber": "1234567890",
4
	"email": "[email protected]",
5
	"subject": "Math",
6
	"school": "UP Public School"
7
}' | http post \
8
	'http://localhost:8081/api/v1/Teacher/invite' \
9
	'content-type: application/json'
Copied!
This will store the entity in the registry and return the following object:
1
{
2
	"id": "open-saber.registry.invite",
3
	"ver": "1.0",
4
	"ets": 1634198998956,
5
	"params": {
6
		"resmsgid": "",
7
		"msgid": "3ee6a76f-d6c8-4262-a7ee-ddbe66fcb127",
8
		"err": "",
9
		"status": "SUCCESSFUL",
10
		"errmsg": ""
11
	},
12
	"responseCode": "OK",
13
	"result": { "Teacher": { "osid": "1-9d6099fc-2c01-4714-bceb-55ff28c482f9" } }
14
}
Copied!
Important variables in the response body:
Field
In
Type
Description
result.{entity-type}.osid
body
string
The ID of the create entity in the registry, used for retrieval and modification of the entity
Requesting Access To An Entity's Data
A client application can request access to an entity's data through an OAuth 2.0 flow by creating a scope in the registry that maps (via the User Property mapper) the scope to give the client permission to access the data.
To go through the consent flow, we must first decide which scope to request. In this case, we will be requesting the openid scope to get access to all the public fields of the entity. Then, we must construct a URL to request the entity to grant us access to their data as follows:
The following example has been indented and split into multiple lines for readability only.
1
# Keycloak's consent endpoint
2
http://localhost:8080/auth/realms/sunbird-rc/protocol/openid-connect/auth?
3
 scope=openid& # The space separated list of scopes we want the entity to grant us access to
4
 response_type=code& # Return an authorization code once the entity grants access
5
 redirect_uri=*& # Send the code to this URL
6
 client_id=registry-frontend # The client requesting access to the entity's data
Copied!
Here is what the URL looks like when it's url-encoded:
http://localhost:8080/auth/realms/sunbird-rc/protocol/openid-connect/auth?scope=openid&response_type=code&redirect_uri=*&client_id=registry-frontend
To go through the consent flow, click on the URL and login as an entity. In this case, we can login as the Teacher entity we created in the Creating An Entity section - enter 1234567890 as the username and [email protected] as the password.
Here, registry-frontend is the preconfigured client we use to make requests to keycloak and [email protected] is the default password for all entities.
Once you have authenticated yourself as the Teacher, you will see a consent screen, asking you to grant access to Registry Frontend. Click YES to grant access to the client and continue with the consent flow.
Once you click YES, it will redirect you to http://localhost:8080/auth/*. You will see an error page, as we have not setup a frontend application to parse the response and request an access token automatically. For this example (and to gain a better understanding of how the consent flow works), we will parse keycloak's response manually.
Notice that the URL query parameters contain two variables: session_state and code. The code parameter is of most importance here - it is a one-time code that will allow us to retrieve an access token with access to the entity's data. Copy the value of the code parameter (everything after code= in the URL). To retrieve an access token, we make the following request:
cURL
1
curl --location \
2
	--request POST \
3
	--header 'content-type: application/x-www-form-urlencoded' \
4
	--data 'client_id=registry-frontend' \
5
	--data 'code={code}' \
6
	--data 'redirect_uri=*' \
7
	--data 'grant_type=authorization_code' \
8
	'http://localhost:8080/auth/realms/sunbird-rc/protocol/openid-connect/token'
Copied!
HTTPie
1
http --form post \
2
	'http://localhost:8080/auth/realms/sunbird-rc/protocol/openid-connect/token' \
3
	'content-type: application/x-www-form-urlencoded' \
4
	'client_id=registry-frontend' \
5
	'code={code}' \
6
	'redirect_uri=*' \
7
	'grant_type=authorization_code'
Copied!
If you get a invalid_grant: Code not valid error, just go through the consent flow again. The code expires quickly, so try to make the request for the access token as soon as you get redirected to the redirect URL!
This API call should return a JSON object as follows:
1
{
2
	"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk...2cSSaBKuB58I2OYDGw",
3
	"expires_in": 300,
4
	"not-before-policy": 0,
5
	"refresh_expires_in": 1800,
6
	"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lk...9HulwVv12bBDUdU_nidZXo",
7
	"scope": "openid email profile",
8
	"session_state": "300f8a46-e430-4fd6-92aa-a2d337d7343e",
9
	"token_type": "Bearer"
10
}
Copied!
Important variables in the response body:
Field
In
Type
Description
access_token
body
string
Access token used to retrieve/update entity
expires_in
body
number
Number of seconds before the access token will be declared invalid
token_type
body
string
Should be Bearer, else we have gotten the wrong token
scope
body
string
This should contain openid, and this means we successfully got user consent!
Once we have the access token, we can start retrieving and modifying entity data.
Authenticating As An Entity
We can authenticate as entities using the Authenticate As Entity API Endpoint. This step is only required if consent is turned off for the frontend client.
So to authenticate as the Teacher entity we just created, we would make the following API call:
cURL
1
curl --location \
2
	--request POST \
3
	--header 'content-type: application/x-www-form-urlencoded' \
4
	--data 'client_id=registry-frontend' \
5
	--data 'username=1234567890' \
6
	--data '[email protected]' \
7
	--data 'grant_type=password' \
8
	'http://localhost:8080/auth/realms/sunbird-rc/protocol/openid-connect/token'
Copied!
HTTPie
1
http --form post \
2
	'http://localhost:8080/auth/realms/sunbird-rc/protocol/openid-connect/token' \
3
	'content-type: application/x-www-form-urlencoded' \
4
	'client_id=registry-frontend' \
5
	'username=1234567890' \
6
	'[email protected]' \
7
	'grant_type=password'
Copied!
Here, registry-frontend is the preconfigured client we use to make requests to keycloak and [email protected]3 is the default password for all entities.
This API call should return a JSON object as follows:
1
{
2
	"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lk...2cSSaBKuB58I2OYDGw",
3
	"expires_in": 300,
4
	"not-before-policy": 0,
5
	"refresh_expires_in": 1800,
6
	"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lk...9HulwVv12bBDUdU_nidZXo",
7
	"scope": "email profile",
8
	"session_state": "300f8a46-e430-4fd6-92aa-a2d337d7343e",
9
	"token_type": "Bearer"
10
}
Copied!
Important variables in the response body:
Field
In
Type
Description
access_token
body
string
Access token used to retrieve/update entity
expires_in
body
number
Number of seconds before the access token will be declared invalid
token_type
body
string
Should be Bearer, else we have gotten the wrong token
scope
body
string
Using this token, what information we can access about the entity
Retrieving An Entity
We can retrieve entities in the registry using the Retrieve Entity API Endpoint.
So to retrieve the entity we created earlier, we would make the following request:
cURL
1
curl --location \
2
	--request GET \
3
	--header 'content-type: application/json' \
4
	--header 'authorization: bearer {access-token}' \
5
	'http://localhost:8081/api/v1/Teacher/{id}'
Copied!
HTTPie
1
http get \
2
	'http://localhost:8081/api/v1/Teacher/{id}' \
3
	'authorization: bearer {access-token}'
Copied!
Replace the {id} above with the entity's osid you saved from the create entity request. Replace the {access-token} with the Teacher entity's access token from the consent/authentication step.
This will return the entity's JSON representation as follows:
1
{
2
	"phoneNumber": "1234567890",
3
	"school": "UP Public School",
4
	"subject": "Math",
5
	"name": "Pranav Agate",
6
	"osid": "{id}",
7
	"osOwner": ["{owner-id}"],
8
	"_osState/school": "DRAFT"
9
}
Copied!
Important variables in the response body:
Field
In
Type
Description
osOwner
body
string
User ID of the entity in Keycloak.
_osState/{field}
body
string
State of an attestable field. Can be DRAFT (when it has not been sent for attestation), ATTESTATION_REQUESTED (when sent for attestation), PUBLISHED (when successfully attested) and REJECTED (when rejected by the attestor)
Updating An Entity
We can update entities in the registry using the Update Entity API Endpoint.
So to update the subject our Teacher entity Pranav Agate teaches to Biology, we would make the following API call:
cURL
1
curl --location \
2
	--request 'PUT' \
3
	--header 'content-type: application/json' \
4
	--header 'authorization: bearer {access-token}' \
5
	--data-raw '{
6
		"name": "Pranav Agate",
7
		"phoneNumber": "1234567890",
8
		"email": "[email protected]",
9
		"subject": "Biology",
10
		"school": "UP Public School"
11
	}' \
12
	'http://localhost:8081/api/v1/Teacher/{id}'
Copied!
HTTPie
1
echo '{
2
	"name": "Pranav Agate",
3
	"phoneNumber": "1234567890",
4
	"email": "[email protected]",
5
	"subject": "Biology",
6
	"school": "UP Public School"
7
}' | http put \
8
	'http://localhost:8081/api/v1/Teacher/{id}' \
9
	'content-type: application/json' \
10
	'authorization: bearer {access-token}'
Copied!
Replace the {id} above with the entity's osid you saved from the create entity request. Replace the {access-token} with the Teacher entity's access token from the consent/authentication step.
We need to send the whole entity and not just the updated fields because that is how RESTful APIs work. A PUT call should replace the existing record in the database with the new object as-is. To know more about this, take a look at the accepted answer on this SO question.
This will update the entity in the registry and return the following object:
1
{
2
	"id": "open-saber.registry.update",
3
	"ver": "1.0",
4
	"ets": 1634371946769,
5
	"params": {
6
		"resmsgid": "",
7
		"msgid": "d51e6e6a-027d-4a42-84bb-2ce00e31d993",
8
		"err": "",
9
		"status": "SUCCESSFUL",
10
		"errmsg": ""
11
	},
12
	"responseCode": "OK"
13
}
Copied!
Making A Claim
To make a claim, we can use the Claim API Endpoint.
First, let us create a Student entity named Prashant Joshi who also goes to UP Public School:
cURL
1
curl --location \
2
	--request 'POST' \
3
	--header 'content-type: application/json' \
4
	--data-raw '{
5
		"name": "Prashant Joshi",
6
		"phoneNumber": "9876543210",
7
		"email": "[email protected]",
8
		"school": "UP Public School"
9
	}' \
10
	'http://localhost:8081/api/v1/Student/invite'
Copied!
HTTPie
1
echo '{
2
	"name": "Prashant Joshi",
3
	"phoneNumber": "9876543210",
4
	"email": "[email protected]",
5
	"school": "UP Public School"
6
}' | http post \
7
	'http://localhost:8081/api/v1/Student/invite' \
8
	'content-type: application/json'
Copied!
Next, we can get an access token for Prashant by either making a POST request to the authentication server (see the Authenticating As An Entity section to know how to do that) OR by requesting entity consent to access their data (see the Requesting Access To An Entity's Data section to know how to do that). The default registry instance setup by the CLI has consent enabled, so we will follow the consent flow to retrieve an access token.
Then, we can send the claim (that Prashant is a student at UP Public School) for attestation by making the following request:
1
curl --location \
2
	--request 'PUT' \
3
	--header 'content-type: application/json' \
4
	--header 'authorization: bearer {access-token}' \
5
	--data-raw '"UP Public School"' \
6
	'http://localhost:8081/api/v1/Student/{id}/school?send=true'
Copied!
HTTPie
1
echo '"UP Public School"' | http put \
2
	'http://localhost:8081/api/v1/Student/{id}/school' \
3
	'content-type: application/json' \
4
	'authorization: bearer {access-token}' \
5
	'send==true'
Copied!
Replace the {id} above with the entity's osid you saved from the create entity request. Replace the {access-token} with the Student entity's access token from the consent/authentication step.
This will send the claim for attestation and return the following object:
1
{
2
	"id": "open-saber.registry.update",
3
	"ver": "1.0",
4
	"ets": 1634371946769,
5
	"params": {
6
		"resmsgid": "",
7
		"msgid": "ksi38Dsl-8dIw-492j-6vlS-84KRe0Csop35",
8
		"err": "",
9
		"status": "SUCCESSFUL",
10
		"errmsg": ""
11
	},
12
	"responseCode": "OK"
13
}
Copied!
If you retrieve the Student entity by following the Retrieving An Entity section, you will get the following object in response:
1
{
2
	"email": "[email protected]",
3
	"name": "Prashant Joshi",
4
	"phoneNumber": "9876543210",
5
	"school": "UP Public School",
6
	"osid": "{id}",
7
	"osOwner": ["{owner-id}"],
8
	"_osClaimId/school": "{claim-id}",
9
	"_osState/school": "ATTESTATION_REQUESTED"
10
}
Copied!
Important variables in the response body:
Field
In
Type
Description
osOwner
body
string
User ID of the entity in Keycloak.
_osState/{field}
body
string
State of an attestable field. Can be DRAFT (when it has not been sent for attestation), ATTESTATION_REQUESTED (when sent for attestation), PUBLISHED (when successfully attested) and REJECTED (when rejected by the attestor)
_osClaimId/{field}
body
string
ID of the claim made on a field, required when attesting the claim.
Attesting/Reject A Claim
We can attest/reject an entity's claim using the Attest Claim API Endpoint.
So to attest the claim we made in the previous section (that Prashant is a student at UP Public School), we make the following request:
cURL
1
curl --location \
2
	--request 'POST' \
3
	--header 'content-type: application/json' \
4
	--header 'authorization: bearer {access-token}' \
5
	--data-raw '{
6
		"action": "GRANT_CLAIM"
7
	}' \
8
	'http://localhost:8081/api/v1/Teacher/claims/{claim-id}/attest'
Copied!
HTTPie
1
echo '{
2
	"action": "GRANT_CLAIM"
3
}' | http post \
4
	'http://localhost:8081/api/v1/Teacher/claims/{claim-id}/attest' \
5
	'content-type: application/json' \
6
	'authorization: bearer {access-token}'
Copied!
Replace the {claim-id} above with the _osClaimId/school you saved from the make a claim request. Replace the {access-token} with the Teacher entity's access token from the consent/authentication step. Replace GRANT_CLAIM with REJECT_CLAIM to reject the claim instead.
This will attest/reject the claim and return a blank HTTP 200 response.
Introduction To Schemas
Creating Your Own Schemas
Last modified 27d ago
Copy link
Edit on GitHub
Contents
Creating An Entity
Requesting Access To An Entity's Data
Authenticating As An Entity
Retrieving An Entity
Updating An Entity
Making A Claim
Attesting/Reject A Claim