Dartmouth API Developer Portal

People-Memberships API

GET returns information about memberships for a person. PUT allows memberships to be created, updated, or deleted. (Currently limited to people who are students.)

Rating

Attribute	Value
Highly Available	Yes
Cache Refresh Interval	60 minutes
Filtering	Yes

GET

GET returns all memberships for the specified netid.

Required Scopes

Scope	Description
urn:dartmouth:people:read.sensitive	This scope is required to access people memberships. Granting of this scope is approved by the Chief Technology Officer of ITC
urn:dartmouth:people:private	This optional scope is required in order to view memberships for FERPA protected identities. Granting of this scope is via the Undergraduate Registrars Office

Request

GET /api/people/{netid}/memberships

Required Headers

Authorization: Bearer {jwt}

Parameters

Parameter Name	Type	Description	Valid values	Required

(Standard filter parameters)

Notes on usage

Memberships are modeled as a subresource of people. Currently it is only possible to get memberships for a particular person. Searching for holders of certain memberships is not available.

The memberships are returned as a collection. When the person does not have memberships associated with their account a status of 200 is returned with an empty array in the payload.

Returns

Status Code	Description
200	The URI parameter {netid} passed in is a valid identity
404	The URI parameter {netid} passed in is NOT a valid identity

Sample Request

https://api.dartmouth.edu/api/people/f00000x/memberships

Sample Return

[
    {
        "member_netid": "f00000x",
        "cache_date": "2019-05-20T18:10:31Z",
        "organization": {
            "namespace": "student_life",
            "organization_type_id": "REL",
            "id": "HILLEL"
        },
        "type": "organization",
        "start_date": "2008-07-16T12:24:02Z",
        "id": "5cc1de4e129f9a1f3aef5330"
    },
    {
        "member_netid": "f00000x",
        "cache_date": "2019-05-20T18:10:31Z",
        "organization": {
            "namespace": "student_life",
            "organization_type_id": "REL",
            "id": "EMAIL"
        },
        "type": "organization",
        "start_date": "2007-06-04T07:39:15Z",
        "id": "5cc1de4e129f9a1f3aef5d8a"
    },
    {
        "member_netid": "f00000x",
        "cache_date": "2019-05-20T18:10:31Z",
        "organization": {
            "namespace": "student_life",
            "organization_type_id": "HC",
            "id": "UHC1"
        },
        "type": "organization",
        "start_date": "2007-06-04T07:39:15Z",
        "id": "5cc1de4e129f9a1f3aef5d9b"
    }
]

PUT

PUT completely replaces memberships for the specified netid. It will create, update, or delete memberships so that current memberships for the associated person match the payload exactly.

Required Scopes

Scope	Description
urn:dartmouth:people:write.sensitive	This scope is required in order to write memberships. Granting of this scope is approved by the Chief Technology Officer of ITC
urn:dartmouth:people:read.sensitive	This scope is required in order to release membership attributes; both read and write scopes are required. Granting of this scope is approved by the Chief Technology Officer of ITC
urn:dartmouth:people:private	This optional scope is required in order to update memberships for FERPA protected identities. Granting of this scope is via the Undergraduate Registrars Office

Request

PUT /api/people/{netid}/memberships

Required Headers

Authorization: Bearer {jwt}
Content-Type: application/json

Payload

PUT payload must be included in the request body. All current memberships must be included and all attributes must be included for each membership. Here is an example payload:

[
   {
        "type": "organization",
        "member_netid": "f00000x",
        "organization": {
            "id": "SHNTHI",
            "organization_type_id": "REL",
            "namespace": "student_life"
        }
    },
   {
        "type": "organization",
        "member_netid": "f00000x",
        "organization": {
            "id": "ALBSTR",
            "organization_type_id": "REL",
            "namespace": "student_life"
        }
    },
   {
        "type": "organization",
        "member_netid": "f00000x",
        "organization": {
            "id": "UHC1",
            "organization_type_id": "HC",
            "namespace": "student_life"
        }
    }
]

Field	Type	Description
type	string	Must be set to "organization"
member_netid	string	Must be equal to {netid} URI parameter
organization.id	string	Must be a valid organization id (from /student_life/organizations API)
organization.organization_type_id	string	Must be a valid organization_type id (from /organization_types API)
organization.namespace	string	Must be set to "student_life"

Notes on usage

The people-memberships API checks the validity of the payload, the presence of required scopes, and confirms that the requested people record exists. It then submits the request to a task queue and returns the url of the task in the location header. The consumer must poll the task until completion.

The task will create, update, or delete memberships so that current memberships for the person match the payload exactly.

Returns

Status Code	Description
202	The URI parameter {netid} passed in is a valid identity, request payload is valid, and the required scopes are in place
404	The URI parameter {netid} passed in is NOT a valid identity
400	Invalid attributes in payload

Sample Request

https://api.dartmouth.edu/api/people/d10073q/memberships

Sample Return

{
    "status": "accepted"
}

Sample Response Header

Location: /api/tasks/5cddb466b68a450c3b102bfd

Task Monitoring

After a PUT request has been accepted, the consumer must poll the task until completion using the following request:

GET /api/tasks/{id}

Here is an example using the task id from above:

https://api.dartmouth.edu/api/tasks/5cddb466b68a450c3b102bfd

Sample Incomplete Task

For incomplete tasks, path is null:

{
    "status": "accepted",
    "path": null,
    "id": "5cddb466b68a450c3b102bfd"
}

Sample Successfull Task

For successfully completed tasks, path is set to the url of the resource that was updated and status provides details of the operation(s) completed.

{
    "status": "SUCCESS: 2 memberships added for f00000x",
    "path": "https://api-dev.dartmouth.edu/api/people/f00000x/memberships",
    "id": "5cddb466b68a450c3b102bfd"
}

Sample Failed Task

For failed tasks, path is set to the url of the resource that was supposed to be updated and status provides details of the failure.

{
    "status": "FAILURE: invalid json payload: [{'type': 'organization', 'member_netid': 'f00000xx', 'organization': {'id': 'EORTHO', 'organization_type_id': 'REL', 'namespace': 'student_lifex'}}, {'type': 'organization', 'member_netid': 'f00000x', 'organization': {'id': 'EMAIL', 'organization_type_id': 'REL', 'namespace': 'student_life'}}, {'type': 'organization', 'member_netid': 'f00000x', 'organization': {'id': 'SHNTHI', 'organization_type_id': 'REL', 'namespace': 'student_life'}}, {'type': 'organization', 'member_netid': 'f00000x', 'organization': {'id': 'ALBSTR', 'organization_type_id': 'REL', 'namespace': 'student_life'}}]",
    "path": "https://api-dev.dartmouth.edu/api/people/f00000x/memberships",
    "id": "5ce408ccb68a450c3b102c06"
}