Self Disclosure API manual 1.0.0

Download PDF

Routes

2. Routes#

The Self-disclosure API consists of multiple routes to retrieve data about users. The following sections explain the individual routes. You can find a corresponding Swagger User Interface (Swagger UI) at https://FQDN/ucsschool/apis/docs#/ of your Self-disclosure API instance.

2.1. How to read#

Each of the following sections makes use of a pattern. For better orientation, this section provides an overview of this pattern. Every URL follows a scheme.

Assume the URL is https://FQDN/ucsschool/apis/self_disclosure/v1/users/0123456789

You can decompose the URL into the parts in Table 2.1.

Table 2.1 Schema of the Self-disclosure API#

Prefix

https://FQDN

Base route URL

/ucsschool/apis/self_disclosure/v1

Suffix

/users/0123456789
Description

Provides a short summary of the requests that you can run against the specified route. The description offers critical information about the received objects.

Base route URL

Provides the non-prefixed URL. The sections about the requests in each chapter provide suffixes to the specified URL.

Requests

Provides a table per suffix that contains the parameters applicable for the resulting URL with additional information about each parameter and the needed HTTP-Method.

Examples

Provides code examples for requests against the specified URL.

2.2. User metadata#

Retrieve metadata about the requested user.

Note

Only people entitled to modify the metadata can retrieve metadata.

2.2.1. Requests#

URL-suffix

/users/id/metadata

Method

Name

Type

Required

Possible values

GET

id

string

yes

Composed URL:

FQDN =     # FQDN or IP-v4 address (string)
ID =       # specific user pseudonym (string)
metadata = f"https://{FQDN}/ucsschool/apis/self_disclosure/v1/users/{ID}/metadata"

2.2.2. Responses#

A valid request returns a JSON object. For example:

{
  "user_id": "2849f8b0-9c98-4710-9fe1-23d4466g9af8",
  "username": "Max.Mustermann",
  "firstname": "Max",
  "lastname": "Mustermann",
  "type": "teacher",
  "school_id": "School1",
  "school_authority": "SchoolAuthority1"
}

The user_id field contains a unique pseudonym for each user. The user_id and the combination of school_id and school_authority are unique across all schools connected to the ID Broker. The other fields are not unique.

The field type refers to a UCS@school object class, that can have one of the following values: teacher, student, admin, staff, teacher-staff.

2.2.3. Examples#

Curl

$ export HOST="[IP or FQDN]"
$ export ID="[ID]"
$ export TOKEN="[TOKEN]"

$ curl -X 'GET' \
> 'http://$HOST/ucsschool/apis/self_disclosure/v1/users/$ID/metadata' \
> -H 'accept: application/json' \
> -H 'Authorization: Bearer $TOKEN'

2.3. User specific group data#

This route retrieves information about the group memberships of the requested user. It also retrieves additional information about the groups listed in the group membership.

2.3.1. Base route URL# 

/ucsschool/apis/self_disclosure/v1

2.3.2. Requests#

URL-suffix:

/users/{id}/groups

Method

Name

Type

Required

Possible values

GET

id

string

yes

Composed URL:

FQDN =        # FQDN or IP-v4 address (string)
ID =          # specific user pseudonym (string)
user_groups = f"https://{FQDN}/ucsschool/apis/self_disclosure/v1/users/{ID}/groups"

2.3.3. Responses#

A valid request returns a JSON object. For example:

{
  "groups": [
    {
      "group_id": "503f1278-9cda-49f6-a749-3af022a7d32b",
      "name": "1a",
      "school_id", "School1",
      "school_authority": "SchoolAuthority1",
      "student_count": 2,
      "type": "school_class"
    }
  ]
}

The returned list shows all groups with their group_id, name and student_count. The field type refers to a UCS@school object class, that can have one of the following values: school_class, workgroup.

2.3.4. Examples#

Curl

$ export HOST="[IP or FQDN]"
$ export ID="[ID]"
$ export TOKEN="[TOKEN]"

$ curl -X 'GET' \
> 'http://$HOST/ucsschool/apis/self_disclosure/v1/users/$ID/groups' \
> -H 'accept: application/json' \
> -H 'Authorization: Bearer $TOKEN'

2.4. Group members#

Retrieve user data about the members of the requested group.

2.4.1. Base route URL# 

/ucsschool/apis/self_disclosure/v1

2.4.2. Requests#

URL-suffix:

/groups/{id}/users

Method

Name

Type

Required

Possible values

GET

id

string

yes

Composed URL:

FQDN =          # FQDN or IP-v4 address (string)Changed aspects:
ID =            # specific group pseudonym (string)
group_members = f"https://{FQDN}/ucsschool/apis/self_disclosure/v1/groups/{ID}/users"

2.4.3. Responses#

A valid request returns a JSON object. For example:

{
  "students": [
    {
      "user_id": "0e49f8b0-9c98-4716-9fe1-23d4466d9af8",
      "username": "Jane.Doe",
      "firstname": "Jane",
      "lastname": "Doe"
    },
    {
      "user_id": "86f753e0-50b3-44cb-807e-2c2556b0e6ca",
      "username": "John.Doe",
      "firstname": "John",
      "lastname": "Doe"
    }
  ],
  "teachers": [
    {
      "user_id": "d8aa843b-9628-42b8-9637-d198c745efa5",
      "username": "Max.Mustermann"
    }
  ]
}

The response lists all members of the requested group, split by role (teacher, student).

2.4.4. Examples#

Curl

$ export HOST="[IP or FQDN]"
$ export ID="[ID]"
$ export TOKEN="[TOKEN]"

$ curl -X 'GET' \
> 'http://$HOST/ucsschool/apis/self_disclosure/v1/groups/$ID/users' \
> -H 'accept: application/json' \
> -H 'Authorization: Bearer $TOKEN'
On this page