Skip to main content

Quick Start Calling Admin API 2.x using Python

Overview

This is a quick start guide for calling Admin API using Python scripting, it will cover the basic operations of the Admin API:Β Β 

Configure Environment with Python and Admin API 2.2​

Once Admin API is installed, we can use Python versions above 3.7+. It is necessary to have the requests library installed or similar. We can use the following command to review our current python version.

python --version

The utility to install packages in Python is called pip, in case you don't have it installed you can follow the instructions in this link.

To install the libraries using pip, you can use the line below.

pip install -U requests

To import it into our script we will use the following imports:

script.py

import requests
import warnings

warnings.filterwarnings('ignore') # setting ignore as a parameter

Information​

GET /

def information(base_url: str) -> dict:
'''
Retrieve API informational data
'''
endpoint = "/"
url = f"{base_url}{endpoint}"

r = requests.get(url, verify=False)

return r.json()

Our output should bring the information from the Restful API.

Sample Output

{
"version": "1.1",
"build": "1.0.0.0"
}

Authenticate to Admin API​

In a new installation, it is necessary to previously register the client to connect, for which we will follow the instructions within the document in Securing Admin API.

Register a new client​

In order to do so, we can add the functionality to our script by adding the following lines.

POST /connect/register

def register(
base_url: str,
client_payload: str,
) -> dict:
'''
Registers a new client

Parameters
----------
'base_url': base_url,
URL where API is hosted
client_payload: dict
The client information
{
'client_id': str,
The client id for the client
'client_secret': str,
The client secret for the client
display_name: str
Display name for client
}
'''
endpoint = "/connect/register"
url = f"{base_url}{endpoint}"

r = requests.post(
url,
data={
"ClientId": client_payload["client_id"],
"ClientSecret": client_payload["client_secret"],
"DisplayName": client_payload["display_name"],
},
verify=False
)

return r.json()

And we can construct our payload as the following example.

Sample input

new_client = {
'client_id': <your_client_id>,
'client_secret': <your_secret>,
'display_name': "Wille",
}

The successful output will be JSON formatted.

Sample output

{
"title": "Registered client 1 successfully.",
"status": 200
}


Token​

Once we register our client according to the parameters specified in the documentΒ Securing Admin API.

We can obtain the token we will use for each API query. Just pass the same ClientID and ClientSecret we use to register it, with two new variables.

Sample input

client_id = <your_client_id>
client_secret = <your_secret>
grant_type = "client_credentials"
scope = "edfi_admin_api/full_access"

POST /connect/token

def token(
base_url: str,
client_id: str,
client_secret: str,
grant_type: str,
scope: str,
) -> dict:
'''
Retrieves a bearer token

Parameters
----------
base_url: str
URL where API is hosted
client_id: str
The client id provided in the register
client_secret: str
The client secret provided in the register
grant_type: str
default "client_credentials"
scope: str
default "edfi_admin_api/full_access"
'''
endpoint = "/connect/token"
url = f"{base_url}{endpoint}"

r = requests.post(
url,
data={
"client_id": client_id,
"client_secret": client_secret,
"grant_type": grant_type,
"scope": scope,
},
verify=False,
)

return r.json()

The outcome will be JSON formatted.

Sample output

{
"access_token": <your_token>,
"token_type": "Bearer",
"expires_in": 3599
}

Then you can use the token as an authentication method, with the header Authorization as the example below.

Vendors​

Retrieve a Listing of Vendors​

See the Endpoints - Admin API page for a complete list of resources and parameters. For this example, we will get a list of providers.Β Β 

GET /v2/vendors

def get_vendors(
base_url: str,
access_token: str,
) -> dict:
'''
Retrieves all vendors

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer

Returns
-------
r: List[Dict[str, str]]
Returns a list of dictionaries from the request
converted from JSON format.
[
{
"vendorId": 0,
"company": "string",
"namespacePrefixes": "string",
"contactName": "string",
"contactEmailAddress": "string",
}
]
'''
endpoint = "/v2/vendors?offset=0&limit=25"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

We will get a list of the vendors, JSON formatted, as in the example below.

Sample output

[
{
"id": 1,
"company": "ACME Education",
"namespacePrefixes": "ACME",
"contactName": "Wile E. Coyote",
"contactEmailAddress": "wile@acme.edu"
}
]


Create a Vendor​

To create a new vendor, we will use the POST verb. Although in this example, it is necessary to pass a dictionary with the required data. Again, you can refer to the link Endpoints - Admin API to successfully create the provider. In our case, we will use the following information.

Sample output

vendor_payload = {
"company": "ACME Education",
"namespacePrefixes": "ACME",
"contactName": "Wile E. Coyote",
"contactEmailAddress": "wile@acme.edu",
}

Which we will pass as a parameter to a function as shown below, or with the method of your choice.

POST /v2/vendors

def create_vendor(
base_url: str,
access_token: str,
payload: dict,
) -> dict:
'''
Creates a vendor based on supplied values

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"company": "string",
"namespacePrefixes": "string",
"contactName": "string",
"contactEmailAddress": "string",
}
'''
endpoint = "/v2/vendors"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.post(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 201 Status Code

Get a vendor​

In the case that you want to retrieve information from one of the vendors, you will need to use the resource ID.

GET /v2/vendors/{id}

def get_vendor(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing vendor using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/vendors"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

In case of success we will obtain an output as follow:

Sample output

{
"Id": 9,
"company": "ACME Education",
"namespacePrefixes": "ACME",
"contactName": "Road Runner",
"contactEmailAddress": "roadrunner@acme.edu"
}

Update a vendor​

For this example, we update the previously created vendor with the following info.

Sample input

vendor_payload = {
"company": "ACME Education",
"namespacePrefixes": "ACME",
"contactName": "Yosemite Sam",
"contactEmailAddress": "yosemitesam@acme.edu",
}

We use as an example the code below.

PUT /v2/vendors/{id}

def edit_vendor(
base_url: str,
access_token: str,
vendor_payload: dict,
id: int
) -> dict:
'''
Updates vendor based on the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
vendor_payload: dict
{
"company": "string",
"namespacePrefixes": "string",
"contactName": "string",
"contactEmailAddress": "string",
}
id: int
Resource identifier
'''
endpoint = "/v2/vendors"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.put(
url=url,
headers=headers,
json=vendor_payload,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code

Delete a vendor​

To delete a vendor you can use the next point, as the example provided below.

/v2/vendors/{id}

def delete_vendor(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Deletes an existing vendor using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/vendors"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.delete(
url=url,
headers=headers,
verify=False,
)

return r.json()

The output will be a confirmation as follows:

Sample output

{
"title": "Vendor deleted successfully"
}

Claim sets​

List all Claims​

To retrieve all the claims we will use the GET verb as follows:

GET /v2/claimsets

def get_claimsets(
base_url: str,
access_token: str,
) -> dict:
'''
Retrieves all claimsets

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer

Returns
-------
r: List[Dict[str, str]]
Returns a list of dictionaries from the request
converted from JSON format.
[
{
"id": 0,
"name": "string",
"_isSystemReserved": false,
"_applications": [
{
"applicationName": "string"
}
]
}
]
'''
endpoint = "/v2/claimsets?offset=0&limit=25"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

The result will be a list of claim sets as the ones shown below:

Sample output

[
{
"id": 1,
"name": "AB Connect",
"_isSystemReserved": true,
"_applications": []
},
...
]

Create a Claim​

For the creation of a claim, we will use the POST verb again, and we will pass a dictionary with the values to store, an example of payload for this case could be like the following.

Sample input

claimset_payload = {
"name": "Acme Learning User"
}

Which we will pass as a parameter in a function like the following:

POST /v2/claimsets

def create_claimset(
base_url: str,
access_token: str,
payload: dict,
) -> dict:
'''
Creates a claimset based on supplied values

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"name": "string"
}
'''
endpoint = "/v2/claimsets"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.post(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 201 Status Code

Retrieve a claim set​

To retrieve the claim information, we will use the Claims ID, the example would be as follows.

GET /v2/claimsets/{id}

def get_claimset(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing claimset using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/claimsets"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

In case of success we will obtain an output as follow:

Sample output

{
"resourceClaims": [
{
"id": 9,
"name": "educationStandards",
"actions": [
{
"name": "Read",
"enabled": true
},
{
"name": "Create",
"enabled": true
}
],
"_defaultAuthorizationStrategiesForCRUD": [
{
"actionId": 1,
"actionName": "Create",
"authorizationStrategies": [
{
"authStrategyId": 4,
"authStrategyName": "NamespaceBased",
"isInheritedFromParent": false
}
]
},
{
"actionId": 2,
"actionName": "Read",
"authorizationStrategies": [
{
"authStrategyId": 1,
"authStrategyName": "NoFurtherAuthorizationRequired",
"isInheritedFromParent": false
}
]
},
{
"actionId": 3,
"actionName": "Update",
"authorizationStrategies": [
{
"authStrategyId": 4,
"authStrategyName": "NamespaceBased",
"isInheritedFromParent": false
}
]
},
{
"actionId": 4,
"actionName": "Delete",
"authorizationStrategies": [
{
"authStrategyId": 4,
"authStrategyName": "NamespaceBased",
"isInheritedFromParent": false
}
]
},
{
"actionId": 5,
"actionName": "ReadChanges",
"authorizationStrategies": [
{
"authStrategyId": 1,
"authStrategyName": "NoFurtherAuthorizationRequired",
"isInheritedFromParent": false
}
]
}
],
"authorizationStrategyOverridesForCRUD": [],
"children": []
}
],
"id": 1,
"name": "Acme Learning User",
"_isSystemReserved": false,
"_applications": [
{
"applicationName": "Acme Learning"
}
]
}

Update a claim set​

In case you want to update some info from the previous claim set. For this example, we will use the next input.

Sample input

claimset_payload = {
"name": "Updated-ClaimSet"
}

And the code to update goes as follows.

PUT /v2/claimsets/{id}

def edit_claimset(
base_url: str,
access_token: str,
payload: dict,
id: int,
) -> dict:
'''
Updates a claimset based on resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"name": "string"
}
'''
endpoint = "/v2/claimsets"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.put(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code

Delete a claim set​

To delete a claim set you can use the example below.

DELETE /v2/claimset/{id}

def delete_claimset(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Deletes an existing claimset using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/claimsets"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.delete(
url=url,
headers=headers,
verify=False,
)

return r.json()

The confirmation message.

Sample output

{
"title": "ClaimSet deleted successfully"
}

Import a Claim set​

For importing a claim, we will use the POST verb again. An example of payload for this case could be like the following.

Sample output

claimset_import_payload = {
"name": "Acme Learning User Imported",
"resourceClaims": [
{
"name": "educationStandards",
"actions": [
{
"name": "read",
"enabled": True
},
{
"name": "create",
"enabled": True
}
]
}
]
}

And the code to import goes as follows.

POST /v2/claimset/{id}

def import_claimset(
base_url: str,
access_token: str,
payload: dict,
) -> dict:
'''
Imports a claimset based on supplied values

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"name": "string",
"resourceClaims": [
{
"name": "string",
"actions": [
{
"name": "string",
"enabled": true
}
],
"authorizationStrategyOverridesForCRUD": [
{
"actionId": 0,
"actionName": "string",
"authorizationStrategies": [
{
"authStrategyId": 0,
"authStrategyName": "string",
"isInheritedFromParent": true
}
]
}
],
"children": [
"string"
]
}
]
}
'''
endpoint = "/v2/claimsets/import"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.post(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

Export a Claim set​

For exporting a claim, we will use the GET verb. An example of payload for this case could be like the following.

GET /v2/claimsets

def export_claimset(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Exports an existing claimset using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/claimsets"
url = f"{base_url}{endpoint}/`{id}`/export"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

In case of success we will obtain an output as follow:

Sample output

{
"resourceClaims": [
{
"id": 9,
"name": "educationStandards",
"actions": [
{
"name": "Read",
"enabled": true
},
{
"name": "Create",
"enabled": true
}
],
"_defaultAuthorizationStrategiesForCRUD": [
{
"actionId": 1,
"actionName": "Create",
"authorizationStrategies": [
{
"authStrategyId": 4,
"authStrategyName": "NamespaceBased",
"isInheritedFromParent": false
}
]
},
{
"actionId": 2,
"actionName": "Read",
"authorizationStrategies": [
{
"authStrategyId": 1,
"authStrategyName": "NoFurtherAuthorizationRequired",
"isInheritedFromParent": false
}
]
},
{
"actionId": 3,
"actionName": "Update",
"authorizationStrategies": [
{
"authStrategyId": 4,
"authStrategyName": "NamespaceBased",
"isInheritedFromParent": false
}
]
},
{
"actionId": 4,
"actionName": "Delete",
"authorizationStrategies": [
{
"authStrategyId": 4,
"authStrategyName": "NamespaceBased",
"isInheritedFromParent": false
}
]
},
{
"actionId": 5,
"actionName": "ReadChanges",
"authorizationStrategies": [
{
"authStrategyId": 1,
"authStrategyName": "NoFurtherAuthorizationRequired",
"isInheritedFromParent": false
}
]
}
],
"authorizationStrategyOverridesForCRUD": [],
"children": []
}
],
"id": 1,
"name": "Acme Learning User",
"_isSystemReserved": false,
"_applications": [
{
"applicationName": "Acme Learning"
}
]
}

ODS Instances​

Retrieve a Listing of ODS instances​

See the Endpoints - Admin API page for a complete list of resources and parameters. For this example, we will get a list of providers.Β Β 

GET /v2/odsInstances

def get_ods_instance(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing ods instance using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/odsInstances"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

We will get a list of the ods instances, JSON formatted, as in the example below.

Sample output

[
{
'id': 1,
'name': 'Ods Instance 1',
'instanceType': 'ODS'
}
]

Create an ODS Instances​

To create a new ods instance, we will use the POST verb.

Sample output

odsinstance_payload = {
"name": "Ods Instance 1",
"instanceType": "ODS",
"connectionString": "valid connection string"
}

Which we will pass as a parameter to a function as shown below, or with the method of your choice.

POST /v2/odsInstances

def create_ods_instance(
base_url: str,
access_token: str,
payload: dict,
) -> dict:
'''
Creates an ODS instance based on supplied values

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"name": "string",
"instanceType": "string",
"connectionString": "string"
}
'''
endpoint = "/v2/odsInstances"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.post(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 201 Status Code

Get an ODS Instance​

In the case that you want to retrieve information from one of the ods instances, you will need to use the resource ID.

GET /v2/odsInstances/{id}

def get_ods_instance(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing ods instance using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/odsInstances"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

In case of success we will obtain an output as follow:

Sample output

{
'odsInstanceContexts': [

],
'odsInstanceDerivatives': [

],
'id': 1,
'name': 'Ods Instance 1',
'instanceType': 'ODS'
}

Get ODS Instance Applications​

In the case that you want to retrieve information from one of the ODS instance applications, you will need to use the resource ID.

GET /v2/odsInstances/{id}

def get_ods_instance_applications(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing ods instance applications using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/odsInstances"
url = f"{base_url}{endpoint}/`{id}`/applications"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

In case of success we will obtain an output as follow:

Sample output

[
{
'id': 1,
'applicationName': 'Acme Learning',
'claimSetName': 'Acme Learning User',
'educationOrganizationIds': [
0
],
'vendorId': 1,
'profileIds': [

],
'odsInstanceIds': [
1
]
}
]

Update an ODS Instance​

You can use the following code to update the information in the ODS instance.

PUT /v2/odsInstances/{id}

def edit_ods_instance(
base_url: str,
access_token: str,
payload: dict,
id: int,
) -> dict:
'''
Updates an ods instance based on resource id

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"name": "string",
"instanceType": "string",
"connectionString": "string"
}
id: int
Resource ID
'''
endpoint = "/v2/odsInstances"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}
r = requests.put(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code

Delete an ODS Instance​

To delete a ods instance you can use the next point, as the example provided below.

/v2/odsInstances/{id}

def delete_ods_instance(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Deletes an existing ods instance using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/odsInstances"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.delete(
url=url,
headers=headers,
verify=False,
)

return r.json()

The output will be a confirmation as follows:

Sample output

{
"title": "Ods Instance deleted successfully"
}

ODS Instance Derivatives​

Retrieve a Listing of ODS instance derivatives​

See the Endpoints - Admin API page for a complete list of resources and parameters. For this example, we will get a list of providers.Β Β 

GET /v2/odsInstanceDerivatives

def get_ods_instance_derivatives(
base_url: str,
access_token: str,
) -> dict:
'''
Retrieves ods instance derivatives

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer

Returns
-------
r: List[Dict[str, str]]
Returns a list of dictionaries from the request
converted from JSON format.
[
[
{
"id": 0,
"odsInstanceId": 0,
"derivativeType": "string"
}
]
]
'''
endpoint = "/v2/odsInstanceDerivatives?offset=0&limit=25"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

We will get a list of the ods instances, JSON formatted, as in the example below.

Sample output

[
{
'id': 2,
'odsInstanceId': 1,
'derivativeType': 'ReadReplica'
}
]

Create an ODS Instance derivatives​

To create a new ods instance, we will use the POST verb.

Sample output

odsinstancederivative_payload = {
"odsInstanceId": 1,
"derivativeType": "ReadReplica",
"connectionString": "Server=localhost;Database=EdFi_Ods;Integrated Security=True;"
}

Which we will pass as a parameter to a function as shown below, or with the method of your choice.

POST /v2/odsInstanceDerivatives

def create_ods_instance_derivative(
base_url: str,
access_token: str,
payload: dict,
) -> dict:
'''
Creates an ODS instance derivative based on supplied values

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"odsInstanceId": 0,
"derivativeType": "string",
"connectionString": "string"
}
'''
endpoint = "/v2/odsInstanceDerivatives"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.post(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 201 Status Code

Get an ODS Instance derivative​

In the case that you want to retrieve information from one of the ods instances, you will need to use the resource ID.

GET /v2/odsInstanceDerivatives/{id}

def get_ods_instance_derivative(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing ods instance derivative using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/odsInstanceDerivatives"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

In case of success we will obtain an output as follow:

Sample output

{
'id': 1,
'odsInstanceId': 1,
'derivativeType': 'ReadReplica'
}

Update an ODS Instance derivative​

You can use the following code to update the information in the ODS instance derivative.

PUT /v2/odsInstanceDerivatives/{id}

def edit_ods_instance_derivative(
base_url: str,
access_token: str,
payload: dict,
id: int,
) -> dict:
'''
Updates an ods instance derivative based on resource id

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"odsInstanceId": 0,
"derivativeType": "string",
"connectionString": "string"
}
id: int
Resource ID
'''
endpoint = "/v2/odsInstanceDerivatives"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}
r = requests.put(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code

Delete an ODS Instance derivative​

To delete a ods instance derivative you can use the next point, as the example provided below.

/v2/odsInstanceDerivatives/{id}

def delete_ods_instance_derivative(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Deletes an existing ods instance derivative using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/odsInstanceDerivatives"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.delete(
url=url,
headers=headers,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code

ODS Instance Contexts​

Retrieve a Listing of ODS instance contexts​

See the Endpoints - Admin API page for a complete list of resources and parameters. For this example, we will get a list of providers.

GET /v2/odsInstanceContexts

def get_ods_instance_contexts(
base_url: str,
access_token: str,
) -> dict:
'''
Retrieves ods instance contexts

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer

Returns
-------
r: List[Dict[str, str]]
Returns a list of dictionaries from the request
converted from JSON format.
[
{
"id": 0,
"odsInstanceId": 1,
"contextKey": "contextKeyText",
"contextValue": "2024"
}
]
'''
endpoint = "/v2/odsInstanceContexts?offset=0&limit=25"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

We will get a list of the ods instances, JSON formatted, as in the example below.

Sample output

[
{
'id': 1,
'odsInstanceId': 1,
'contextKey': 'contextKeyText',
'contextValue': '2024'
}
]

Create an ODS Instance Context​

To create a new ods instance, we will use the POST verb.

Sample output

odsinstancecontext_payload = {
"odsInstanceId": 1,
"contextKey": "contextKeyText",
"contextValue": "2024"
}

Which we will pass as a parameter to a function as shown below, or with the method of your choice.

POST /v2/odsInstanceContexts

def create_ods_instance_context(
base_url: str,
access_token: str,
payload: dict,
) -> dict:
'''
Creates an ODS instance context based on supplied values

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"odsInstanceId": 0,
"contextKey": "string",
"contextValue": "string"
}
'''
endpoint = "/v2/odsInstanceContexts"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.post(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 201 Status Code

Get an ODS Instance Context​

In the case that you want to retrieve information from one of the ods instance context, you will need to use the resource ID.

GET /v2/odsInstanceContexts/{id}

def get_ods_instance_context(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing ods instance context using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/odsInstanceContexts"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

In case of success we will obtain an output as follow:

Sample output

{
'id': 1,
'odsInstanceId': 1,
'contextKey': 'contextKeyText',
'contextValue': '2024'
}

Update an ODS Instance Context​

You can use the following code to update the information in the ODS instance context.

PUT /v2/odsInstanceContexts/{id}

def edit_ods_instance_context(
base_url: str,
access_token: str,
payload: dict,
id: int,
) -> dict:
'''
Updates an ods instance context based on resource id

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"odsInstanceId": 0,
"contextKey": "string",
"contextValue": "string"
}
id: int
Resource ID
'''
endpoint = "/v2/odsInstanceContexts"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}
r = requests.put(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code

Delete an ODS Instance Context​

To delete a ods instance context you can use the next point, as the example provided below.

/v2/odsInstanceContexts/{id}

def delete_ods_instance_context(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Deletes an existing ods instance context using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/odsInstanceContexts"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.delete(
url=url,
headers=headers,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code

Applications​

Create an Application and Set of Credentials​

To create an application, we use the POST verb, and we will pass it a dictionary with the values to store, an example of payload for this case could be the following.

Sample data create application

application_payload = {
"applicationName": "Acme Learning",
"vendorId": 1,
"claimSetName": "Acme Learning User",
"educationOrganizationIds": [
0
],
"odsInstanceIds": [
0
]
}

Which we will use inside a variable to pass it inside a function like a payload.

POST /v2/applications

def create_application(
base_url: str,
access_token: str,
payload: dict,
) -> dict:
'''
Creates a application based on supplied values

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"applicationName": "string",
"vendorId": 0,
"claimSetName": "string",
"profileId": 0,
"educationOrganizationIds": [
0
]
}
'''
endpoint = "/v2/applications"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}
r = requests.post(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r.json()

The result of the code above it will give you an output as follows.

Sample output

{
"applicationId": 4,
"key": "ZQeSgtdaj2GI",
"secret": "XHuwnSJLxkWUKfXzYAXkSkaG"
}

Retrieve application data​

Where you can obtain the key and secret from the response, and save the application ID. If you need to verify that your app was created, you can use the code as follows with the App ID.

GET /v2/applications/{id}

def get_application(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing application using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/applications"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

The confirmation outcome will be like the following:

Sample output

{
"applicationId": 1,
"applicationName": "Acme Learning",
"claimSetName": "Acme Learning User",
"profileName": null,
"educationOrganizationId": 0,
"odsInstanceName": null
}

Update an application​

You can use the following code to update the information in the application.

PUT /v2/applications/{id}

def edit_application(
base_url: str,
access_token: str,
payload: dict,
id: int,
) -> dict:
'''
Updates an application based on resource id

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"applicationName": "string",
"vendorId": 0,
"claimSetName": "string",
"profileId": 0,
"educationOrganizationIds": [
0
]
}
id: int
Resource ID
'''
endpoint = "/v2/applications"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}
r = requests.put(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r.json()

As a result, we will obtain a 200 Status Code

Delete an application​

To delete an application the example will be the following.

DELETE /v2/applications/{id}

def delete_application(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Deletes an existing application using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/applications"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.delete(
url=url,
headers=headers,
verify=False,
)

return r.json()

The output will be as follow:

Sample output

{
"title": "Application deleted successfully"
}


Refresh application credentials​

In case you want to refresh your credentials or get a new ones you can use the next endpoint.

PUT /v2/applications/{id}/reset-credential

def reset_application_credentials(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing application using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/applications"
url = f"{base_url}{endpoint}/`{id}`/reset-credential"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.put(
url=url,
headers=headers,
verify=False,
)

return r.json()

The resulting output will again print the new secret keys.

Sample output

{
"applicationId": 4,
"key": "ZQeSgtdaj2GI",
"secret": "GeAepnauytC1NqaJV2HKfhit"
}

Create multiple applications using a CSV file​

In case you want to create multiple applications, you can use the following template and code sample to do so:

CSV file template β†’Β apps.csv

Columns description

  • Name: (Required) The application name
  • VendorId: (Required) Set the vendor id as numeric value. e.g. 2
  • ClamsetName: (Required) The claimset to be used. e.g. SIS Vendor
  • ProfileIds: (Optional) List with the profile ids. This cell is not required, but in case you need to set it the format should be a single id or multiple. In case of multiple values, use the dash to separate them, e.g. 10-20-30
  • EdOrgIds: (Required) List with the eduction organization ids. This cell is required, the format should be a single id or multiple. In case of multiple values, use the dash to separate them, e.g. 10023-20020-304040
  • OdsInstanceIds:Β (Required) List with the ods instance ids. This cell is required, the format should be a single id or multiple. In case of multiple values, use the dash to separate them, e.g. 10023-20020-304040
info

import_applications.py

import pandas
import math
import numbers
import applications #script where you have the create_application

def import_applications(
base_url: str,
access_token: str,
file_path: str,
) -> dict:
'''
Creates applications from csv file

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
file_path: str
String with the CSV location
'''
df = pandas.read_csv(file_path)
for index, row in df.iterrows():
profileIds = []
print(row)
if "-" in str(row[3]):
profileIds = [int(i) for i in row[3].split('-')]
elif isinstance(row[3], numbers.Number) and not math.isnan(row[3]):
profileIds = [int(row[3])]
elif isinstance(row[3], numbers.Number):
profileIds = []

edOrgIds = [int(i) for i in row[4].split('-')]
odsIds = [int(i) for i in row[5].split('-')]

application_payload = {
"applicationName": row[0],
"vendorId": row[1],
"claimSetName": row[2],
"profileIds": profileIds,
"educationOrganizationIds": edOrgIds,
"odsInstanceIds": odsIds
}
print(application_payload)
print(applications.create_application(base_url, access_token, application_payload))

As a result, we will obtain multiple 201 Status Code

Profiles​

Retrieve a Listing of Profiles​

See the Endpoints - Admin API page for a complete list of resources and parameters. For this example, we will get a list of providers.

GET /v2/profiles

def get_profiles(
base_url: str,
access_token: str,
) -> dict:
'''
Retrieves profiles

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer

Returns
-------
r: List[Dict[str, str]]
Returns a list of dictionaries from the request
converted from JSON format.
[
{
"id": 0,
"name": "string"
}
]
'''
endpoint = "/v2/profiles?offset=0&limit=25"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

We will get a list of the ods instances, JSON formatted, as in the example below.

Sample output

[
{
'id': 1,
'name': 'Test-Profile'
}
]

Create a profile​

To create a new profile, we will use the POST verb.

Sample output

profile_payload = {
"name": "Test-Profile",
"definition": "<Profile name=\"Test-Profile\"><Resource name=\"Resource1\"><ReadContentType memberSelection=\"IncludeOnly\"><Collection name=\"Collection1\" memberSelection=\"IncludeOnly\"><Property name=\"Property1\" /><Property name=\"Property2\" /></Collection></ReadContentType><WriteContentType memberSelection=\"IncludeOnly\"><Collection name=\"Collection2\" memberSelection=\"IncludeOnly\"><Property name=\"Property1\" /><Property name=\"Property2\" /></Collection></WriteContentType></Resource></Profile>"
}

Which we will pass as a parameter to a function as shown below, or with the method of your choice.

POST /v2/profiles

def create_profile(
base_url: str,
access_token: str,
payload: dict,
) -> dict:
'''
Creates a profile based on supplied values

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"name": "Test-Profile",
"definition": "<Profile name=\"Test-Profile\"><Resource name=\"Resource1\"><ReadContentType memberSelection=\"IncludeOnly\"><Collection name=\"Collection1\" memberSelection=\"IncludeOnly\"><Property name=\"Property1\" /><Property name=\"Property2\" /></Collection></ReadContentType><WriteContentType memberSelection=\"IncludeOnly\"><Collection name=\"Collection2\" memberSelection=\"IncludeOnly\"><Property name=\"Property1\" /><Property name=\"Property2\" /></Collection></WriteContentType></Resource></Profile>"
}
'''
endpoint = "/v2/profiles"
url = f"{base_url}{endpoint}"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.post(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 201 Status Code

Get Profile​

In the case that you want to retrieve information from one of the profiles, you will need to use the resource ID.

GET /v2/profiles/{id}

def get_profile(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Get an existing profile using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/profiles"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.get(
url=url,
headers=headers,
verify=False,
)

return r.json()

In case of success we will obtain an output as follow:

Sample output

{
'definition': '<Profile name="Test-Profile"><Resource name="Resource1"><ReadContentType memberSelection="IncludeOnly"><Collection name="Collection1" memberSelection="IncludeOnly"><Property name="Property1" /><Property name="Property2" /></Collection></ReadContentType><WriteContentType memberSelection="IncludeOnly"><Collection name="Collection2" memberSelection="IncludeOnly"><Property name="Property1" /><Property name="Property2" /></Collection></WriteContentType></Resource></Profile>',
'id': 1,
'name': 'Test-Profile'
}

Update a Profile​

You can use the following code to update the information in the profile.

PUT /v2/profiles/{id}

def edit_profile(
base_url: str,
access_token: str,
payload: dict,
id: int,
) -> dict:
'''
Updates a profile based on resource id

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
payload: dict
{
"name": "Test-Profile",
"definition": "<Profile name=\"Test-Profile\"><Resource name=\"Resource1\"><ReadContentType memberSelection=\"IncludeOnly\"><Collection name=\"Collection1\" memberSelection=\"IncludeOnly\"><Property name=\"Property1\" /><Property name=\"Property2\" /></Collection></ReadContentType><WriteContentType memberSelection=\"IncludeOnly\"><Collection name=\"Collection2\" memberSelection=\"IncludeOnly\"><Property name=\"Property1\" /><Property name=\"Property2\" /></Collection></WriteContentType></Resource></Profile>"
}
id: int
Resource ID
'''
endpoint = "/v2/profiles"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}
r = requests.put(
url=url,
headers=headers,
json=payload,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code

Delete a Profile​

To delete a profile you can use the next point, as the example provided below.

/v2/profiles/{id}

def delete_profile(
base_url: str,
access_token: str,
id: int,
) -> dict:
'''
Deletes an existing profile using the resource identifier

Parameters
----------
base_url: str
URL where API is hosted
access_token: str
String with the authorization token bearer
id: int
Resource identifier
'''
endpoint = "/v2/profiles"
url = f"{base_url}{endpoint}/`{id}`"
headers = {
'Authorization': f'Bearer {access_token}',
'Content-type': 'application/json',
'Accept': 'text/plain',
}

r = requests.delete(
url=url,
headers=headers,
verify=False,
)

return r

As a result, we will obtain a 200 Status Code