To generate Python client bindings using the OpenAPI generator:
git clone https://github.com/Internet2/comanage-registry.git pushd comanage-registry git checkout develop popd mkdir mnt cp comanage-registry/app/Config/Schema/restapiv1.yaml mnt/restapiv1.yaml docker run \ --rm \ -v $PWD/mnt:/mnt openapitools/openapi-generator-cli generate \ -i /mnt/restapiv1.yaml \ -g python \ -o /mnt/out/python \ --additional-properties=packageName=comanage_registry_restapiv1_client |
To create a virtual environment with the client API package installed:
python -m venv myenv source myenv/bin/activate pip install --upgrade pip sudo chown -R `whoami` local/out pip install -e mnt/out/python/ |
The Python binding specific documentation will be rendered in markdown with the entry point in the file mnt/out/python/README.md
Below is an example Python script that exercises parts of the API.
Before executing the script you must create a new API User in the working CO.
Be sure to edit the values for SERVER, CO_ID, USERNAME, PASSWORD, and IDENTIFIER. See the comments in the code.
import comanage_registry_restapiv1_client from comanage_registry_restapiv1_client.rest import ApiException from comanage_registry_restapiv1_client.models import CoGroupRequest from comanage_registry_restapiv1_client.models import CoGroupsRequestType from comanage_registry_restapiv1_client.models import CoGroupMemberRequest from comanage_registry_restapiv1_client.models import CoGroupMemberRequestPerson from comanage_registry_restapiv1_client.models import CoGroupMembersRequestType from pprint import pprint # The Registry server URL. It should include the /registry path. SERVER = "https://registry.example.org/registry" # The CO in which to work. CO_ID = 2 # The REST API username. USERNAME = "" # The REST API password. PASSWORD = "" # The value of an Identifier attached to an existing CO Person. IDENTIFIER = "albert.einstein" # Defining the host is optional and defaults to https://localhost/registry # See configuration.py for a list of all supported configuration parameters. configuration = comanage_registry_restapiv1_client.Configuration( host=SERVER, username=USERNAME, password=PASSWORD, ) # Enter a context with an instance of the API client. with comanage_registry_restapiv1_client.ApiClient(configuration) as api_client: # Create an instance of the API class. api_instance = comanage_registry_restapiv1_client.V1Api(api_client) # Create a new group and record its ID. newGroup = CoGroupRequest( version="1.0", co_id=str(CO_ID), name="API Test Group", description="An API Test", open=False, status="Active", ) newGroupRequest = CoGroupsRequestType( request_type="CoGroups", version="1.0", co_groups=[newGroup] ) try: api_response = api_instance.add_co_group(newGroupRequest) newGroupId = int(api_response.id) print("The response of add_co_group:\n") pprint(api_response) except ApiException as e: print("Exception when calling add_co_group: %s\n" % e) # Find the CO Person ID for identifier try: api_response = api_instance.get_co_people(coid=2, search_identifier=IDENTIFIER) coPersonId = int(api_response.co_people[0].id) print("The response of get_co_people:\n") pprint(api_response) except ApiException as e: print("Exception when calling get_co_people: %s\n" % e) # Determine if the CO Person is a member of the new group. isMember = False try: api_response = api_instance.get_co_group_members(copersonid=coPersonId) memberships = api_response.co_group_members for m in memberships: groupId = int(m.co_group_id) if groupId == newGroupId: isMember = True break print("The response of get_co_group_members\n") pprint(api_response) except ApiException as e: print("Exception when calling get_co_group_members: %s\n" % e) # If not already a member then add the CO Person to the Co Group. if not isMember: memberRequestPerson = CoGroupMemberRequestPerson(type="CO", id=str(coPersonId)) newMembership = CoGroupMemberRequest( version="1.0", co_group_id=str(newGroupId), person=memberRequestPerson, member=True, owner=False, ) newMembershipRequest = CoGroupMembersRequestType( request_type="CoGroupMembers", version="1.0", co_group_members=[newMembership], ) try: api_response = api_instance.add_co_group_member(newMembershipRequest) print("The response of add_co_group_member:\n") pprint(api_response) except ApiException as e: print("Exception when calling add_co_group_member: %s\n" % e) |
Suppose you have two COs with these COUs:
CO 4:
CO 5:
The REST call for a Platform API User (CO 1) might look like this:
$ curl -s -X GET -u co_1.platform_rest_user:password https://example.com/registry/cous.json | python -m json.tool { "Cous": [ { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "4", "Created": "2020-11-16 12:00:00", "Deleted": false, "Description": "College of Letters and Science", "Id": "6", "Lft": "11", "Modified": "2020-11-16 12:00:00", "Name": "L and S", "Revision": "0", "Rght": "18", "Version": "1.0" }, { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "4", "Created": "2020-11-16 12:00:19", "Deleted": false, "Description": "Physics Department", "Id": "7", "Lft": "12", "Modified": "2020-11-16 12:00:19", "Name": "Physics", "ParentId": "6", "Revision": "0", "Rght": "15", "Version": "1.0" }, { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "4", "Created": "2020-11-16 12:00:43", "Deleted": false, "Description": "Astronomy Department", "Id": "8", "Lft": "13", "Modified": "2020-11-16 12:00:43", "Name": "Astronomy", "ParentId": "7", "Revision": "0", "Rght": "14", "Version": "1.0" }, { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "4", "Created": "2020-11-16 12:00:58", "Deleted": false, "Description": "Chemistry Department", "Id": "9", "Lft": "16", "Modified": "2020-11-16 12:00:58", "Name": "Chemistry", "ParentId": "6", "Revision": "0", "Rght": "17", "Version": "1.0" }, { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "5", "Created": "2020-11-16 12:09:18", "Deleted": false, "Description": "Optics Team", "Id": "12", "Lft": "21", "Modified": "2020-11-16 12:09:18", "Name": "Optics Team", "Revision": "0", "Rght": "24", "Version": "1.0" }, { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "5", "Created": "2020-11-16 12:09:45", "Deleted": false, "Description": "Diffraction Team", "Id": "13", "Lft": "22", "Modified": "2020-11-16 12:09:45", "Name": "Diffraction Team", "ParentId": "12", "Revision": "0", "Rght": "23", "Version": "1.0" }, { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "5", "Created": "2020-11-16 12:10:31", "Deleted": false, "Description": "Stoarge Ring Team", "Id": "14", "Lft": "25", "Modified": "2020-11-16 12:10:31", "Name": "Storage Ring Team", "Revision": "0", "Rght": "26", "Version": "1.0" } ], "ResponseType": "Cous", "Version": "1.0" } |
The same call with a Privileged CO API User (CO 5) will result in a 401 Unauthorized since the Privileged CO API User does not have access to all COs:
$ curl --verbose -X GET -u co_5.my_rest_user:password https://example.com/registry/cous.json > GET /registry/cous.json HTTP/2 > Authorization: Basic Y29fNS5teV9yZXN0X3VzZXI6ZzBmei1vODJuLXVpNzQtNnliaw== > User-Agent: curl/7.64.0 > Accept: */* > < HTTP/2 401 |
Instead the Privileged CO API User should specify the (numeric) CO to which the user has access using the View (per CO) syntax
$ curl -s -X GET -u co_5.my_rest_user:password https://example.com/registry/cous.json?coid=5 | python -m json.tool { "Cous": [ { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "5", "Created": "2020-11-16 12:09:18", "Deleted": false, "Description": "Optics Team", "Id": "12", "Lft": "21", "Modified": "2020-11-16 12:09:18", "Name": "Optics Team", "Revision": "0", "Rght": "24", "Version": "1.0" }, { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "5", "Created": "2020-11-16 12:09:45", "Deleted": false, "Description": "Diffraction Team", "Id": "13", "Lft": "22", "Modified": "2020-11-16 12:09:45", "Name": "Diffraction Team", "ParentId": "12", "Revision": "0", "Rght": "23", "Version": "1.0" }, { "ActorIdentifier": "phil.hines@comanage.incommon.training", "CoId": "5", "Created": "2020-11-16 12:10:31", "Deleted": false, "Description": "Stoarge Ring Team", "Id": "14", "Lft": "25", "Modified": "2020-11-16 12:10:31", "Name": "Storage Ring Team", "Revision": "0", "Rght": "26", "Version": "1.0" } ], "ResponseType": "Cous", "Version": "1.0" } |
A Privileged CO API User (CO 5) may add a new COU for CO 5 like this:
$ cat cou_request.json { "RequestType":"Cous", "Version":"1.0", "Cous": [ { "Version":"1.0", "CoId":"5", "ParentId":"14", "Name":"Undulator Team", "Description":"Undulator Team" } ] } $ curl \ -d @cou_request.json \ -X POST -H 'Content-type: application/json' \ -u co_5.my_rest_user:password \ https://example.com/registry/cous.json | python -m json.tool { "Id": "16", "ObjectType": "Cou", "ResponseType": "NewObject", "Version": "1.0" } |