Using The APIs
The following guide walks you through the different Registry APIs using the example of a student-teacher registry.
Inviting An Entity
We can create entities in the registry using the Invite 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
HTTPie
This will store the entity in the registry and return the following object:
Important variables in the response body:
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.
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 Inviting An Entity section - enter 1234567890 as the username and test as the password.
Here,
registry-frontendis the preconfigured client we use to make requests to keycloak andtestis 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
HTTPie
If you get a
invalid_grant: Code not validerror, just go through the consent flow again. Thecodeexpires 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:
Important variables in the response body:
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
HTTPie
Here,
registry-frontendis the preconfigured client we use to make requests to keycloak andtestis the default password for all entities.
This API call should return a JSON object as follows:
Important variables in the response body:
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
HTTPie
Replace the
{id}above with the entity'sosidyou saved from the create entity request. Replace the{access-token}with theTeacherentity's access token from the consent/authentication step.
This will return the entity's JSON representation as follows:
Important variables in the response body:
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
HTTPie
Replace the
{id}above with the entity'sosidyou saved from the create entity request. Replace the{access-token}with theTeacherentity'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:
Deleting An Entity
We can delete entities in the registry using the Delete Entity API Endpoint.
So to delete the subject our Teacher entity, we would make the following API call:
cURL
HTTPie
Replace the
{id}above with the entity'sosidyou saved from the create entity request. Replace the{access-token}with theTeacherentity's access token from the consent/authentication step.
This will delete the entity in the registry and return a blank HTTP 200 response.
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
HTTPie
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:
HTTPie
Replace the
{id}above with the entity'sosidyou saved from the create entity request. Replace the{access-token}with theStudententity's access token from the consent/authentication step.
This will send the claim for attestation and return the following object:
If you retrieve the Student entity by following the Retrieving An Entity section, you will get the following object in response:
Important variables in the response body:
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
HTTPie
Replace the
{claim-id}above with the_osClaimId/schoolyou saved from the make a claim request. Replace the{access-token}with theTeacherentity's access token from the consent/authentication step. ReplaceGRANT_CLAIMwithREJECT_CLAIMto reject the claim instead.
This will attest/reject the claim and return a blank HTTP 200 response.
Last updated