OpenAPI Generator

Python Client Bindings

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.

api_demo.py 
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)


Other Examples

Suppose you have two COs with these COUs:

CO 4:

  • L and S
    • Chemistry
    • Physics
      • Astronomy

CO 5:

  • Optics Team
    • Diffraction Team
  • Storage Ring Team

Listing

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"
}

Adding

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"
}


  • No labels