COmanage Registry CORE API serves as a central hub for API management, ensuring proper validation, seamless interaction with other system models, efficient data processing, and maintaining overall data integrity. This recipe describes how COmanage Registry might be configured with CORE API to manage CoPerson records.

Recipe Ingredients

  • This recipe requires COmanage Registry version 4.0.0 or later.
Recipe Steps
  1. Install Plugins
    Install the CORE API Plugin

  2. Configure API User
    Configure an API User

  3. Configure CORE API
    Configure CORE API

  4. GET/Read CoPerson
    Fetch a CoPerson and its associated data

  5. PUT/Update CoPerson
    Update a CoPerson

Like what you see? See our other recipes!

Recipe Steps

1. Install Plugins

COmanage Registry supports several types of plugins in order to easily customize and extend Registry functionality. Plugins may be one of three types, each of which has a different process for being installed and enabled: Supported Core Plugins, Supported Non-core Plugins, and External Plugins.

Step overview

For this recipe, you will need to install and enable the following plugin. Since this is a Core plugin, it is  likely already available for your use.

Plugins needed for this recipe

NAMETYPEPLUGIN CLASSDESCRIPTION
CORE APICOREOther A collection of higher level APIs that provide transaction-oriented operations
RESOURCES for step 1. Install Plugins

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

TECHNICAL GUIDES

2. Configure API User

Step overview

For this use case we will use the bare minimum set of configuration options that have to be set. API Users are set at the CO level.

API User Basic Settings

  • Sign into Registry and navigate to the CO (if necessary)

  • Create an API User

    1. The administrator clicks the API Users  configuration

      The administrator clicks the API Users configuration

    2. Clicks the Add API User  top action link


    3. Add the necessary configurations




RESOURCES for step 2. Configure API User

See the following resources for details to complete this recipe step:

USE GUIDES / OVERVIEWS

3. Configure CORE API

All plugins have basic settings that are are related to the plugin’s Class. In addition, some plugins have plugin-specific settings to configure the specifics related to the plugin.

Step overview

For this use case we will use the bare minimum set of configuration options that have to be set. API Users are set at the CO level.

API User Basic Settings

  1. Sign into Registry and navigate to the CO (if necessary)

  2. Create a CORE API instance

    1. The administrator clicks the API Users  configuration

    b. Clicks the Add Core API  top action link

    c. Add the necessary configurations



  3. Core API configurations


    1. Pick the Person Write API option to enable both edit and read capabilities

    2. Choose the API User we configured in step 2
    3. Pick the identifier that will be used to query for the CoPerson
    4. Configure the Response Type  to the Full Profile option






4. GET/Read CO Person

Step overview

The CORE API GET request aims to retrieve detailed information about a CoPerson from the COmanage registry database, identified by a unique identifier within the URL. The information is obtained in JSON format.

Sample request:

curl -X GET "https://example.com/registry/api/co/2/core/v1/people/650bf0892fe9c579f6e38716c66a0558f859b1b04964f15d1b1fecbcc80d3bfc@example.org" \
-H "Cache-Control: no-cache" \
-H "Accept: application/json" \
-H "Authorization: Basic $(echo -n 'apiuser_test:apiuser_test_pass' | base64)"

Main Components:

  • Host ({{host}}): The base URL or domain where the API is hosted. Replace {{host}} with the actual domain.

  • Unique Identifier ({uniqueIdentifier}): A unique string identifying the person in the registry. This is embedded within the URL.

  • Credentials: {{apiuser_test}}:{{apiuser_test_pass}} are placeholders for the API user's username and password. These should be replaced with actual credentials and encoded in Base64 for the Authorization header.

JSON Response:

{
  "CoPerson": {
    "meta": {
      "id": 2954,
      "created": "2023-06-22 15:19:50",
      "modified": "2023-06-22 15:19:50",
      "co_person_id": null,
      "revision": 0,
      "deleted": false,
      "actor_identifier": "co_2.test"
    },
    "co_id": 2,
    "status": "A",
    "timezone": "Europe\/Rome",
    "date_of_birth": null
  },
  "CoGroupMember": [
    {
      "meta": {
        "id": 3831,
        "created": "2023-06-22 15:19:50",
        "modified": "2023-06-22 15:19:50",
        "co_group_member_id": null,
        "revision": 0,
        "deleted": false,
        "actor_identifier": "co_2.test",
        "source_org_identity_id": null
      },
      "co_group_id": 56,
      "member": true,
      "owner": false,
      "valid_from": null,
      "valid_through": null,
      "co_group_nesting_id": null
    },
    {
      "meta": {
        "id": 3832,
        "created": "2023-06-22 15:19:50",
        "modified": "2023-06-22 15:19:50",
        "co_group_member_id": null,
        "revision": 0,
        "deleted": false,
        "actor_identifier": "co_2.test",
        "source_org_identity_id": null
      },
      "co_group_id": 4,
      "member": true,
      "owner": false,
      "valid_from": null,
      "valid_through": null,
      "co_group_nesting_id": null
    }
  ],
  "EmailAddress": [
    {
      "meta": {
        "id": 4459,
        "created": "2023-06-22 15:19:50",
        "modified": "2023-06-22 15:19:50",
        "email_address_id": null,
        "revision": 0,
        "deleted": false,
        "actor_identifier": "co_2.test",
        "source_email_address_id": null
      },
      "mail": "example@mailinator.org",
      "type": "official",
      "verified": true,
      "description": "Some description"
    }
  ],
  "CoPersonRole": [
    {
      "meta": {
        "id": 3351,
        "sponsor_co_person_id": null,
        "created": "2023-06-22 15:19:50",
        "modified": "2023-06-22 15:19:50",
        "co_person_role_id": null,
        "revision": 0,
        "deleted": false,
        "actor_identifier": "co_2.test",
        "source_org_identity_id": null
      },
      "cou_id": null,
      "affiliation": "member",
      "title": null,
      "o": null,
      "ou": null,
      "valid_from": null,
      "valid_through": null,
      "status": "A",
      "ordr": null,
      "manager_co_person_id": null,
      "Address": [],
      "AdHocAttribute": [],
      "TelephoneNumber": []
    }
  ],
  "Identifier": [
    {
      "meta": {
        "id": 4385,
        "created": "2023-06-22 15:19:50",
        "modified": "2023-06-22 15:19:50",
        "identifier_id": null,
        "revision": 0,
        "deleted": false,
        "actor_identifier": "co_2.test",
        "source_identifier_id": null,
        "co_provisioning_target_id": null,
        "co_group_id": null
      },
      "identifier": "650bf0892fe9c579f6e38716c66a0558f859b1b04964f15d1b1fecbcc80d3bfc@example.org",
      "type": "epuid",
      "login": true,
      "status": "A",
      "language": null
    },
    {
      "meta": {
        "id": 4387,
        "created": "2023-06-22 15:19:50",
        "modified": "2023-06-22 15:19:50",
        "identifier_id": null,
        "revision": 0,
        "deleted": false,
        "actor_identifier": "co_2.test",
        "source_identifier_id": null,
        "co_provisioning_target_id": null,
        "co_group_id": null
      },
      "identifier": "john.doe.2@ioigoume.org",
      "type": "uid",
      "login": false,
      "status": "A",
      "language": null
    }
  ],
  "Name": [
    {
      "meta": {
        "id": 12391,
        "created": "2023-06-22 15:19:50",
        "modified": "2023-06-22 15:19:50",
        "name_id": null,
        "revision": 0,
        "deleted": false,
        "actor_identifier": "co_2.test",
        "source_name_id": null
      },
      "honorific": null,
      "given": "John",
      "middle": null,
      "family": "Doe",
      "suffix": null,
      "type": "official",
      "language": "",
      "primary_name": true
    }
  ],
  "Url": [],
  "OrgIdentity": [
    {
      "meta": {
        "id": 10383,
        "created": "2023-06-22 15:19:50",
        "modified": "2023-06-22 15:19:50",
        "org_identity_id": null,
        "revision": 0,
        "deleted": false,
        "actor_identifier": "co_2.test"
      },
      "affiliation": "member",
      "title": null,
      "o": "Organization",
      "ou": null,
      "co_id": 2,
      "status": null,
      "valid_from": null,
      "valid_through": null,
      "date_of_birth": null,
      "manager_identifier": null,
      "sponsor_identifier": null,
      "Address": [],
      "AdHocAttribute": [],
      "EmailAddress": [
        {
          "meta": {
            "id": 4461,
            "created": "2023-06-22 15:19:50",
            "modified": "2023-06-22 15:19:50",
            "email_address_id": null,
            "revision": 0,
            "deleted": false,
            "actor_identifier": "co_2.test",
            "source_email_address_id": null
          },
          "mail": "example@mailinator.com",
          "type": "home",
          "verified": true,
          "description": null
        }
      ],
      "Identifier": [
        {
          "meta": {
            "id": 4386,
            "created": "2023-06-22 15:19:50",
            "modified": "2023-06-22 15:19:50",
            "identifier_id": null,
            "revision": 0,
            "deleted": false,
            "actor_identifier": "co_2.test",
            "source_identifier_id": null,
            "co_provisioning_target_id": null,
            "co_group_id": null
          },
          "identifier": "650bf0892fe9c579f6e38716c66a0558f859b1b04964f15d1b1fecbcc80d3bfc@example.org",
          "type": "epuid",
          "login": true,
          "status": "A",
          "language": null
        }
      ],
      "Name": [
        {
          "meta": {
            "id": 12392,
            "created": "2023-06-22 15:19:50",
            "modified": "2023-06-22 15:19:50",
            "name_id": null,
            "revision": 0,
            "deleted": false,
            "actor_identifier": "co_2.test",
            "source_name_id": null
          },
          "honorific": null,
          "given": "John",
          "middle": null,
          "family": "Doe",
          "suffix": null,
          "type": "official",
          "language": "",
          "primary_name": true
        }
      ],
      "TelephoneNumber": [],
      "Url": []
    }
  ],
  "Password": [],
  "PrivacyIdea": [],
  "SshKey": [],
  "UnixClusterAccount": []
}

5. PUT/Update CO Person

Step overview

The CORE API PUT request aims to update the information about a CoPerson from the COmanage registry database, identified by a unique identifier within the URL. The request payload has to be in JSON format.

Sample request:

curl -X PUT "https://example_incommon.com/registry/api/co/2/core/v1/people/650bf0892fe9c579f6e38716c66a0558f859b1b04964f15d1b1fecbcc80d3bfc@example.org" \
-H "Cache-Control: no-cache" \
-H "Accept: application/json" \
-H "Content-Type: application/json; charset=utf-8" \
-H "Authorization: Basic $(echo -n 'apiuser_test:apiuser_test_pass' | base64)" \
-d '{}'

Main Components:

  • Host Placeholder ({{host}}): The base URL or domain where the API is hosted. Replace {{host}} with the actual domain.
  • Unique Identifier ({uniqueIdentifier}): A unique string that identifies the person in the registry. This identifier is embedded within the URL.
  • Credentials: {{apiuser_test}}:{{apiuser_test_pass}} are placeholders for the API user's username and password. These should be replaced with actual credentials and encoded in Base64 for the Authorization header.


For a PUT/Update request each record MUST include a meta  JSON object with the id  of the record. The rest of the `meta` fields returned from the READ action will be ignored.

5.1 Update CoPerson's existing Email Address

Below we aim to modify the email type attribute of a "CoPerson" entity in COmanage Registry. Initially, the email type is official  and we want to update it to personal . The body of the request will be as presented below:

  1. We will include the entire response as received from the GET request
  2. We will strip out all the metadata fields except from the id 
  3. We will update the value according to our use case


Old Email Type value: official

Updated Email Type value: personal


5.2 Add a new Email Address to CoPerson

Below we aim to add one more email, of type personal, to the CoPerson . The body of the request will be as presented below:

  1. We will include the entire response as received from the GET request
  2. We will strip out all the metadata fields except from the id 
  3. We will append a new JSON object in the `EmailAddress` array. The object will include all the required data. Check Email Address Schema for more details.