openapi: 3.0.0
info:
title: Lookup/Ibis web service group API
version: '1.2'
description: "Methods for querying and manipulating groups.\n\n#### The fetch parameter for groups\n\nAll methods that return groups also accept an optional `fetch`\nparameter that may be used to request additional information about the\ngroups returned. For more details about the general rules that apply to\nthe `fetch` parameter, refer to the `PersonMethods`\ndocumentation.\n\nFor groups the `fetch` parameter may be used to fetch references\nto people, institutions or other groups. In each case, only non-cancelled\npeople, institutions and groups will be included when fetching references.\nThe following references are supported:\n\n* `\"all_members\"` - fetches all the people who are members of the\n group, including members of groups included by the group, and groups\n included by those groups, and so on.\n\n* `\"direct_members\"` - fetches all the people who are direct\n members of the group, not taking into account any included groups.\n\n* `\"members_of_inst\"` - if the group is a membership group for an\n institution, this fetches that institution.\n\n* `\"owning_insts\"` - fetches all the institutions to which the\n group belongs.\n\n* `\"manages_insts\"` - fetches all the institutions that the group\n manages. Typically this only applies to \"Editor\" groups.\n\n* `\"manages_groups\"` - fetches all the groups that this group\n manages. Note that some groups are self-managed, so this may be a\n self-reference.\n\n* `\"managed_by_groups\"` - fetches all the groups that manage this\n group.\n\n* `\"reads_groups\"` - fetches all the groups that this group has\n privileged access to. This means that members of this group can see the\n members of the referenced groups regardless of the membership visibility\n settings.\n\n* `\"read_by_groups\"` - fetches all the groups that have privileged\n access to this group.\n\n* `\"includes_groups\"` - fetches all the groups included by this\n group.\n\n* `\"included_by_groups\"` - fetches all the groups that include\n this group.\n\nAs with person `fetch` parameters, the references may be used\nin a chain by using the \"dot\" notation to fetch additional information\nabout referenced people, institutions or groups. For example\n`\"all_members.email\"` will fetch the email addresses of all members\nof the group. For more information about what can be fetched from\nreferenced people and institutions, refer to the documentation for\n`PersonMethods` and `InstitutionMethods`."
servers:
- url: https://lookup-test.srv.uis.cam.ac.uk/api/v1
description: Test server
- url: https://www.lookup.cam.ac.uk/api/v1
description: Live server
security:
- basicAuth: []
tags:
- name: group
description: "Methods for querying and manipulating groups.\n\n#### The fetch parameter for groups\n\nAll methods that return groups also accept an optional `fetch`\nparameter that may be used to request additional information about the\ngroups returned. For more details about the general rules that apply to\nthe `fetch` parameter, refer to the `PersonMethods`\ndocumentation.\n\nFor groups the `fetch` parameter may be used to fetch references\nto people, institutions or other groups. In each case, only non-cancelled\npeople, institutions and groups will be included when fetching references.\nThe following references are supported:\n\n* `\"all_members\"` - fetches all the people who are members of the\n group, including members of groups included by the group, and groups\n included by those groups, and so on.\n\n* `\"direct_members\"` - fetches all the people who are direct\n members of the group, not taking into account any included groups.\n\n* `\"members_of_inst\"` - if the group is a membership group for an\n institution, this fetches that institution.\n\n* `\"owning_insts\"` - fetches all the institutions to which the\n group belongs.\n\n* `\"manages_insts\"` - fetches all the institutions that the group\n manages. Typically this only applies to \"Editor\" groups.\n\n* `\"manages_groups\"` - fetches all the groups that this group\n manages. Note that some groups are self-managed, so this may be a\n self-reference.\n\n* `\"managed_by_groups\"` - fetches all the groups that manage this\n group.\n\n* `\"reads_groups\"` - fetches all the groups that this group has\n privileged access to. This means that members of this group can see the\n members of the referenced groups regardless of the membership visibility\n settings.\n\n* `\"read_by_groups\"` - fetches all the groups that have privileged\n access to this group.\n\n* `\"includes_groups\"` - fetches all the groups included by this\n group.\n\n* `\"included_by_groups\"` - fetches all the groups that include\n this group.\n\nAs with person `fetch` parameters, the references may be used\nin a chain by using the \"dot\" notation to fetch additional information\nabout referenced people, institutions or groups. For example\n`\"all_members.email\"` will fetch the email addresses of all members\nof the group. For more information about what can be fetched from\nreferenced people and institutions, refer to the documentation for\n`PersonMethods` and `InstitutionMethods`."
paths:
/group/all-groups:
get:
tags:
- group
summary: Return a list of all groups.
description: 'Return a list of all groups.
By default, only a few basic details about each group are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references.'
operationId: Group_allGroups
parameters:
- name: includeCancelled
in: query
description: 'Whether or not to include cancelled
groups. By default, only live groups are returned.'
required: false
schema:
type: boolean
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The requested groups (in groupid order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
groups:
type: array
items:
$ref: '#/components/schemas/Group'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/list:
get:
tags:
- group
summary: Get the groups with the specified IDs or names.
description: 'Get the groups with the specified IDs or names.
By default, only a few basic details about each group are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
The results are sorted by groupid.
NOTE: The URL path length is limited to around 8000 characters,
which limits the number of groups that this method can fetch. Group
IDs are currently 6 characters long, and must be comma separated and
URL encoded, which limits this method to around 800 groups by ID,
but probably fewer by name, depending on the group name lengths.
NOTE: The groups returned may include cancelled groups. It is the
caller''s responsibility to check their cancelled flags.'
operationId: Group_listGroups
parameters:
- name: groupids
in: query
description: 'A comma-separated list of group IDs or
group names (may be a mix of both).'
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The requested groups (in groupid order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
groups:
type: array
items:
$ref: '#/components/schemas/Group'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/modified-groups:
get:
tags:
- group
summary: Find all groups modified between the specified pair of transactions.
description: 'Find all groups modified between the specified pair of transactions.
The transaction IDs specified should be the IDs from two different
requests for the last (most recent) transaction ID, made at different
times, that returned different values, indicating that some Lookup
data was modified in the period between the two requests. This method
then determines which (if any) groups were affected.
By default, only a few basic details about each group are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
NOTE: All data returned reflects the latest available data about each
group. It is not possible to query for old data, or more detailed
information about the specific changes made.'
operationId: Group_modifiedGroups
parameters:
- name: minTxId
in: query
description: 'Include modifications made in transactions
after (but not including) this one.'
required: true
schema:
type: integer
format: int64
- name: maxTxId
in: query
description: 'Include modifications made in transactions
up to and including this one.'
required: true
schema:
type: integer
format: int64
- name: groupids
in: query
description: 'Only include groups with IDs or names in
this list. By default, all modified groups will be included.'
required: false
schema:
type: string
- name: includeCancelled
in: query
description: 'Include cancelled groups. By
default, cancelled groups are excluded.'
required: false
schema:
type: boolean
- name: membershipChanges
in: query
description: 'Include groups whose members have
changed. By default, changes to group memberships are not taken into
consideration.'
required: false
schema:
type: boolean
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The modified groups (in groupid order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
groups:
type: array
items:
$ref: '#/components/schemas/Group'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/search:
get:
tags:
- group
summary: Search for groups using a free text query string.
description: 'Search for groups using a free text query string. This is the same
search function that is used in the Lookup web application.
By default, only a few basic details about each group are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
NOTE: If the query string starts with the prefix `"group:"`, it
is treated as an [LQL query](/lql), allowing
more advanced searches. An LQL query will ignore the
`approxMatches` parameter, but it will respect the value of
`includeCancelled`. In addition, an LQL query will ignore
the `orderBy` parameter, since LQL queries always return
results in ID order.'
operationId: Group_search
parameters:
- name: query
in: query
description: The search string.
required: true
schema:
type: string
- name: approxMatches
in: query
description: 'Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
to `false`. This is ignored for LQL queries.'
required: false
schema:
type: boolean
- name: includeCancelled
in: query
description: 'Flag to allow cancelled groups to
be included. Defaults to `false`.'
required: false
schema:
type: boolean
- name: offset
in: query
description: 'The number of results to skip at the start
of the search. Defaults to 0.'
required: false
schema:
type: integer
format: int32
- name: limit
in: query
description: 'The maximum number of results to return.
Defaults to 100.'
required: false
schema:
type: integer
format: int32
- name: orderBy
in: query
description: 'The order in which to list the results.
This may be `"groupid"`, `"name"` (the default for non-LQL
queries) or `"title"`. This is ignored for LQL queries, which
always return results in groupid order.'
required: false
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The matching groups.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
groups:
type: array
items:
$ref: '#/components/schemas/Group'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/search-count:
get:
tags:
- group
summary: 'Count the number of groups that would be returned by a search using
a free text query string.'
description: 'Count the number of groups that would be returned by a search using
a free text query string.
NOTE: If the query string starts with the prefix `"group:"`, it
is treated as an [LQL query](/lql), allowing
more advanced searches. An LQL query will ignore the
`approxMatches` parameter, but it will respect the value of
`includeCancelled`.'
operationId: Group_searchCount
parameters:
- name: query
in: query
description: The search string.
required: true
schema:
type: string
- name: approxMatches
in: query
description: 'Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
to `false`. This is ignored for LQL queries.'
required: false
schema:
type: boolean
- name: includeCancelled
in: query
description: 'Flag to allow cancelled groups to
be included. Defaults to `false`.'
required: false
schema:
type: boolean
responses:
200:
description: The number of matching groups.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
value:
type: integer
format: int32
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/{groupid}:
get:
tags:
- group
summary: Get the group with the specified ID or name.
description: 'Get the group with the specified ID or name.
By default, only a few basic details about the group are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references of the group.
NOTE: The group returned may be a cancelled group. It is the caller''s
responsibility to check its cancelled flag.'
operationId: Group_getGroup
parameters:
- name: groupid
in: path
description: 'The ID or name of the group to fetch. This
may be either the numeric ID or the short hyphenated group name (for
example `"100656"` or `"cs-editors"`).'
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The requested group or `null` if it was not found.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
group:
$ref: '#/components/schemas/Group'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/{groupid}/cancelled-members:
get:
tags:
- group
summary: 'Get all the cancelled members of the specified group, including
cancelled members of groups included by the group, and groups included
by those groups, and so on.'
description: 'Get all the cancelled members of the specified group, including
cancelled members of groups included by the group, and groups included
by those groups, and so on.
By default, only a few basic details about each member are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references of each person.
NOTE: This method returns only cancelled people. It does not include
people who were removed from the group. Cancelled people are no longer
considered to be current staff, students or accredited visitors, and
are no longer regarded as belonging to any groups or institutions. The
list returned here reflects their group memberships just before they
were cancelled, and so is out-of-date data that should be used with
caution.'
operationId: Group_getCancelledMembers
parameters:
- name: groupid
in: path
description: The ID or name of the group.
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch for each person.'
required: false
schema:
type: string
responses:
200:
description: The group's cancelled members (in identifier order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
people:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/{groupid}/direct-members:
get:
tags:
- group
summary: 'Get the direct members of the specified group, not including members
included via groups included by the group.'
description: 'Get the direct members of the specified group, not including members
included via groups included by the group.
By default, only a few basic details about each member are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references of each person.
NOTE: This method will not include cancelled people.'
operationId: Group_getDirectMembers
parameters:
- name: groupid
in: path
description: The ID or name of the group.
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch for each person.'
required: false
schema:
type: string
responses:
200:
description: The group's direct members (in identifier order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
people:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/{groupid}/members:
get:
tags:
- group
summary: 'Get all the members of the specified group, including members of
groups included by the group, and groups included by those groups,
and so on.'
description: 'Get all the members of the specified group, including members of
groups included by the group, and groups included by those groups,
and so on.
By default, only a few basic details about each member are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references of each person.
NOTE: This method will not include cancelled people.'
operationId: Group_getMembers
parameters:
- name: groupid
in: path
description: The ID or name of the group.
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch for each person.'
required: false
schema:
type: string
responses:
200:
description: The group's members (in identifier order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
people:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/group/{groupid}/token:
get:
tags:
- group
summary: 'Get a signed JSON Web Token (JWT) with the group as subject and
specified audience, only if authorized user/group has permission to edit
the group.'
description: 'Get a signed JSON Web Token (JWT) with the group as subject and
specified audience, only if authorized user/group has permission to edit
the group.'
operationId: Group_getToken
parameters:
- name: groupid
in: path
description: The ID of the group.
required: true
schema:
type: string
- name: aud
in: query
description: Audience for the signed JWT.
required: true
schema:
type: string
responses:
200:
description: The serialized JWT
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
value:
type: string
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
components:
schemas:
Identifier:
type: object
properties:
scheme:
type: string
description: The identifier's scheme (e.g., "crsid").
value:
type: string
description: The identifier's value in that scheme (e.g., a specific CRSid value).
description: Class representing a person's identifier, for use by the web service API.
ContactRow:
type: object
properties:
description:
type: string
description: The contact row's text.
bold:
type: boolean
description: 'Flag indicating if the contact row''s text is normally displayed in
bold.'
italic:
type: boolean
description: 'Flag indicating if the contact row''s text is normally displayed in
italics.'
addresses:
type: array
items:
type: string
description: 'A list of the contact row''s addresses. This will always be non-null,
but may be an empty list.'
emails:
type: array
items:
type: string
description: 'A list of the contact row''s email addresses. This will always be
non-null, but may be an empty list.'
people:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'A list of the people referred to by the contact row. This will always
be non-null, but may be an empty list.'
phoneNumbers:
type: array
items:
$ref: '#/components/schemas/ContactPhoneNumber'
description: 'A list of the contact row''s phone numbers. This will always be
non-null, but may be an empty list.'
webPages:
type: array
items:
$ref: '#/components/schemas/ContactWebPage'
description: 'A list of the contact row''s web pages. This will always be non-null,
but may be an empty list.'
description: 'Class representing an institution contact row, for use by the web
services API.'
Error:
type: object
properties:
status:
type: integer
format: int32
description: The HTTP error status code.
code:
type: string
description: A short textual description of the error status code.
message:
type: string
description: A short textual description of the error message (typically one line).
details:
type: string
description: The full details of the error (e.g., a Java stack trace).
description: Class representing an error returned by the web service API.
Attribute:
type: object
properties:
attrid:
type: integer
format: int64
description: The unique internal identifier of the attribute.
scheme:
type: string
description: The attribute's scheme.
value:
type: string
description: The attribute's value (except for binary attributes).
comment:
type: string
description: Any comment associated with the attribute.
instid:
type: string
description: 'For a person attribute, the optional institution that the attribute
is associated with. This will not be set for institution attributes.'
visibility:
type: string
description: 'For a person attribute, it''s visibility (`"private"`,
`"institution"`, `"university"` or `"world"`). This
will not be set for institution attributes.'
effectiveFrom:
type: string
format: date-time
description: For time-limited attributes, the date from which it takes effect.
effectiveTo:
type: string
format: date-time
description: For time-limited attributes, the date after which it is no longer effective.
owningGroupid:
type: string
description: 'For a person attribute, the ID of the group that owns it (typically
the user agent group that created it).'
description: 'Class representing an attribute of a person or institution returned by
the web service API. Note that for institution attributes, the instid,
visibility and owningGroupid fields will be `null`.'
ContactWebPage:
type: object
properties:
url:
type: string
description: The web page's URL.
label:
type: string
description: The web page's label (link text) if set.
description: 'Class representing a web page referred to by an institution contact row,
for use by the web service API.'
Person:
type: object
properties:
cancelled:
type: boolean
description: Flag indicating if the person is cancelled.
identifier:
allOf:
- $ref: '#/components/schemas/Identifier'
- description: The person's primary identifier (typically
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-cambridge/refs/heads/main/openapi/university-of-cambridge-group-api-openapi.yml