{ "openapi": "3.0.0", "info": { "title": "Lookup/Ibis web service API", "version": "1.2" }, "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" } ], "paths": { "/group/all-groups": { "get": { "tags": [ "group" ], "summary": "Return a list of all groups.", "description": "Return a list of all groups.\n\nBy default, only a few basic details about each group are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references.", "operationId": "Group_allGroups", "parameters": [ { "name": "includeCancelled", "in": "query", "description": "Whether or not to include cancelled\ngroups. By default, only live groups are returned.", "required": false, "schema": { "type": "boolean" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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.\n\nBy default, only a few basic details about each group are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references.\n\nThe results are sorted by groupid.\n\nNOTE: The URL path length is limited to around 8000 characters,\nwhich limits the number of groups that this method can fetch. Group\nIDs are currently 6 characters long, and must be comma separated and\nURL encoded, which limits this method to around 800 groups by ID,\nbut probably fewer by name, depending on the group name lengths.\n\nNOTE: The groups returned may include cancelled groups. It is the\ncaller's responsibility to check their cancelled flags.", "operationId": "Group_listGroups", "parameters": [ { "name": "groupids", "in": "query", "description": "A comma-separated list of group IDs or\ngroup names (may be a mix of both).", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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.\n\nThe transaction IDs specified should be the IDs from two different\nrequests for the last (most recent) transaction ID, made at different\ntimes, that returned different values, indicating that some Lookup\ndata was modified in the period between the two requests. This method\nthen determines which (if any) groups were affected.\n\nBy default, only a few basic details about each group are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references.\n\nNOTE: All data returned reflects the latest available data about each\ngroup. It is not possible to query for old data, or more detailed\ninformation about the specific changes made.", "operationId": "Group_modifiedGroups", "parameters": [ { "name": "minTxId", "in": "query", "description": "Include modifications made in transactions\nafter (but not including) this one.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxTxId", "in": "query", "description": "Include modifications made in transactions\nup 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\nthis list. By default, all modified groups will be included.", "required": false, "schema": { "type": "string" } }, { "name": "includeCancelled", "in": "query", "description": "Include cancelled groups. By\ndefault, cancelled groups are excluded.", "required": false, "schema": { "type": "boolean" } }, { "name": "membershipChanges", "in": "query", "description": "Include groups whose members have\nchanged. By default, changes to group memberships are not taken into\nconsideration.", "required": false, "schema": { "type": "boolean" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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\nsearch function that is used in the Lookup web application.\n\nBy default, only a few basic details about each group are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references.\n\nNOTE: If the query string starts with the prefix `\"group:\"`, it\nis treated as an [LQL query](/lql), allowing\nmore advanced searches. An LQL query will ignore the\n`approxMatches` parameter, but it will respect the value of\n`includeCancelled`. In addition, an LQL query will ignore\nthe `orderBy` parameter, since LQL queries always return\nresults 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\nmatching in the search, causing more results to be returned. Defaults\nto `false`. This is ignored for LQL queries.", "required": false, "schema": { "type": "boolean" } }, { "name": "includeCancelled", "in": "query", "description": "Flag to allow cancelled groups to\nbe included. Defaults to `false`.", "required": false, "schema": { "type": "boolean" } }, { "name": "offset", "in": "query", "description": "The number of results to skip at the start\nof the search. Defaults to 0.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "The maximum number of results to return.\nDefaults to 100.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "orderBy", "in": "query", "description": "The order in which to list the results.\nThis may be `\"groupid\"`, `\"name\"` (the default for non-LQL\nqueries) or `\"title\"`. This is ignored for LQL queries, which\nalways return results in groupid order.", "required": false, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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\na free text query string.", "description": "Count the number of groups that would be returned by a search using\na free text query string.\n\nNOTE: If the query string starts with the prefix `\"group:\"`, it\nis treated as an [LQL query](/lql), allowing\nmore advanced searches. An LQL query will ignore the\n`approxMatches` parameter, but it will respect the value of\n`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\nmatching in the search, causing more results to be returned. Defaults\nto `false`. This is ignored for LQL queries.", "required": false, "schema": { "type": "boolean" } }, { "name": "includeCancelled", "in": "query", "description": "Flag to allow cancelled groups to\nbe 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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.\n\nBy default, only a few basic details about the group are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of the group.\n\nNOTE: The group returned may be a cancelled group. It is the caller's\nresponsibility to check its cancelled flag.", "operationId": "Group_getGroup", "parameters": [ { "name": "groupid", "in": "path", "description": "The ID or name of the group to fetch. This\nmay be either the numeric ID or the short hyphenated group name (for\nexample `\"100656\"` or `\"cs-editors\"`).", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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\ncancelled members of groups included by the group, and groups included\nby those groups, and so on.", "description": "Get all the cancelled members of the specified group, including\ncancelled members of groups included by the group, and groups included\nby those groups, and so on.\n\nBy default, only a few basic details about each member are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of each person.\n\nNOTE: This method returns only cancelled people. It does not include\npeople who were removed from the group. Cancelled people are no longer\nconsidered to be current staff, students or accredited visitors, and\nare no longer regarded as belonging to any groups or institutions. The\nlist returned here reflects their group memberships just before they\nwere cancelled, and so is out-of-date data that should be used with\ncaution.", "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\nattributes 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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\nincluded via groups included by the group.", "description": "Get the direct members of the specified group, not including members\nincluded via groups included by the group.\n\nBy default, only a few basic details about each member are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of each person.\n\nNOTE: 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\nattributes 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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\ngroups included by the group, and groups included by those groups,\nand so on.", "description": "Get all the members of the specified group, including members of\ngroups included by the group, and groups included by those groups,\nand so on.\n\nBy default, only a few basic details about each member are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of each person.\n\nNOTE: 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\nattributes 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.\nThis may be just a simple textual value or it may contain more complex\nentities 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\nspecified audience, only if authorized user/group has permission to edit\nthe group.", "description": "Get a signed JSON Web Token (JWT) with the group as subject and\nspecified audience, only if authorized user/group has permission to edit\nthe 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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/all-attr-schemes": { "get": { "tags": [ "institution" ], "summary": "Return a list of all the institution attribute schemes available.", "description": "Return a list of all the institution attribute schemes available.\nThe `schemeid` values of these schemes may be used in the\n`fetch` parameter of other methods that return institutions.", "operationId": "Institution_allAttributeSchemes", "responses": { "200": { "description": "All the available institution attribute schemes (in precedence\norder).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "attributeSchemes": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeScheme" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/all-insts": { "get": { "tags": [ "institution" ], "summary": "Return a list of all institutions.", "description": "Return a list of all institutions.\n\nBy default, only a few basic details about each institution are\nreturned, but the optional `fetch` parameter may be used\nto fetch additional attributes or references.", "operationId": "Institution_allInsts", "parameters": [ { "name": "includeCancelled", "in": "query", "description": "Whether or not to include cancelled\ninstitutions. By default, only live institutions are returned.", "required": false, "schema": { "type": "boolean" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested institutions (in instid order).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/list": { "get": { "tags": [ "institution" ], "summary": "Get the institutions with the specified IDs.", "description": "Get the institutions with the specified IDs.\n\nBy default, only a few basic details about each institution are\nreturned, but the optional `fetch` parameter may be used\nto fetch additional attributes or references.\n\nThe results are sorted by ID.\n\nNOTE: The URL path length is limited to around 8000 characters, and\nan instid is up to 8 characters long. Allowing for comma separators\nand URL encoding, this limits the number of institutions that this\nmethod may fetch to around 700.\n\nNOTE: The institutions returned may include cancelled institutions.\nIt is the caller's responsibility to check their cancelled flags.", "operationId": "Institution_listInsts", "parameters": [ { "name": "instids", "in": "query", "description": "A comma-separated list of instids.", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested institutions (in instid order).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/modified-insts": { "get": { "tags": [ "institution" ], "summary": "Find all institutions modified between the specified pair of\ntransactions.", "description": "Find all institutions modified between the specified pair of\ntransactions.\n\nThe transaction IDs specified should be the IDs from two different\nrequests for the last (most recent) transaction ID, made at different\ntimes, that returned different values, indicating that some Lookup\ndata was modified in the period between the two requests. This method\nthen determines which (if any) institutions were affected.\n\nBy default, only a few basic details about each institution are\nreturned, but the optional `fetch` parameter may be used\nto fetch additional attributes or references.\n\nNOTE: All data returned reflects the latest available data about each\ninstitution. It is not possible to query for old data, or more\ndetailed information about the specific changes made.", "operationId": "Institution_modifiedInsts", "parameters": [ { "name": "minTxId", "in": "query", "description": "Include modifications made in transactions\nafter (but not including) this one.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxTxId", "in": "query", "description": "Include modifications made in transactions\nup to and including this one.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "instids", "in": "query", "description": "Only include institutions with instids in\nthis list. By default, all modified institutions will be included.", "required": false, "schema": { "type": "string" } }, { "name": "includeCancelled", "in": "query", "description": "Include cancelled institutions. By\ndefault, cancelled institutions are excluded.", "required": false, "schema": { "type": "boolean" } }, { "name": "contactRowChanges", "in": "query", "description": "Include institutions whose contact\nrows have changed. By default, changes to institution contact rows are\nnot taken into consideration.", "required": false, "schema": { "type": "boolean" } }, { "name": "membershipChanges", "in": "query", "description": "Include institutions whose members\nhave changed. By default, changes to institutional memberships are not\ntaken into consideration.", "required": false, "schema": { "type": "boolean" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The modified institutions (in instid order).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/search": { "get": { "tags": [ "institution" ], "summary": "Search for institutions using a free text query string.", "description": "Search for institutions using a free text query string. This is the\nsame search function that is used in the Lookup web application.\n\nBy default, only a few basic details about each institution are\nreturned, but the optional `fetch` parameter may be used\nto fetch additional attributes or references.\n\nNOTE: If the query string starts with the prefix `\"inst:\"`, it\nis treated as an [LQL query](/lql), allowing\nmore advanced searches. An LQL query will ignore the\n`approxMatches` and `attributes` parameters, but\nit will respect the value of `includeCancelled`. In\naddition, an LQL query will ignore the `orderBy` parameter,\nsince LQL queries always return results in ID order.", "operationId": "Institution_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\nmatching in the search, causing more results to be returned. Defaults\nto `false`. This is ignored for LQL queries.", "required": false, "schema": { "type": "boolean" } }, { "name": "includeCancelled", "in": "query", "description": "Flag to allow cancelled institutions\nto be included. Defaults to `false`.", "required": false, "schema": { "type": "boolean" } }, { "name": "attributes", "in": "query", "description": "A comma-separated list of attributes to\nconsider when searching. If this is `null` (the default) then\nall attribute schemes marked as searchable will be included. This is\nignored for LQL queries.", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "The number of results to skip at the start\nof the search. Defaults to 0.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "The maximum number of results to return.\nDefaults to 100.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "orderBy", "in": "query", "description": "The order in which to list the results.\nThis may be either `\"instid\"` or `\"name\"` (the default for\nnon-LQL queries). This is ignored for LQL queries, which always return\nresults in instid order.", "required": false, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The matching institutions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/search-count": { "get": { "tags": [ "institution" ], "summary": "Count the number of institutions that would be returned by a search\nusing a free text query string.", "description": "Count the number of institutions that would be returned by a search\nusing a free text query string.\n\nNOTE: If the query string starts with the prefix `\"inst:\"`, it\nis treated as an [LQL query](/lql), allowing\nmore advanced searches. An LQL query will ignore the\n`approxMatches` and `attributes` parameters, but\nit will respect the value of `includeCancelled`.", "operationId": "Institution_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\nmatching in the search, causing more results to be returned. Defaults\nto `false`. This is ignored for LQL queries.", "required": false, "schema": { "type": "boolean" } }, { "name": "includeCancelled", "in": "query", "description": "Flag to allow cancelled institutions\nto be included. Defaults to `false`.", "required": false, "schema": { "type": "boolean" } }, { "name": "attributes", "in": "query", "description": "A comma-separated list of attributes to\nconsider when searching. If this is `null` (the default) then\nall attribute schemes marked as searchable will be included. This is\nignored for LQL queries.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The number of matching institutions.", "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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/{instid}": { "get": { "tags": [ "institution" ], "summary": "Get the institution with the specified ID.", "description": "Get the institution with the specified ID.\n\nBy default, only a few basic details about the institution are\nreturned, but the optional `fetch` parameter may be used\nto fetch additional attributes or references of the institution.\n\nNOTE: The institution returned may be a cancelled institution. It is\nthe caller's responsibility to check its cancelled flag.", "operationId": "Institution_getInst", "parameters": [ { "name": "instid", "in": "path", "description": "The ID of the institution to fetch.", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested institution or `null` if it was not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "institution": { "$ref": "#/components/schemas/Institution" } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/{instid}/cancelled-members": { "get": { "tags": [ "institution" ], "summary": "Get all the cancelled members of the specified institution.", "description": "Get all the cancelled members of the specified institution.\n\nBy default, only a few basic details about each member are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of each person.\n\nNOTE: This method returns only cancelled people. It does not include\npeople who were removed from the institution. Cancelled people are no\nlonger considered to be current staff, students or accredited visitors,\nand are no longer regarded as belonging to any groups or institutions.\nThe list returned here reflects their institutional memberships just\nbefore they were cancelled, and so is out-of-date data that should be\nused with caution.", "operationId": "Institution_getCancelledMembers", "parameters": [ { "name": "instid", "in": "path", "description": "The ID of the institution.", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch for each person.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The institution'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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/{instid}/contact-rows": { "get": { "tags": [ "institution" ], "summary": "Get all the contact rows of the specified institution.", "description": "Get all the contact rows of the specified institution.\n\nAny addresses, email addresses, phone numbers and web pages\nassociated with the contact rows are automatically returned, as\nwell as any people referred to by the contact rows.\n\nIf any of the contact rows refer to people, then only a few basic\ndetails about each person are returned, but the optional\n`fetch` parameter may be used to fetch additional\nattributes or references of each person.\n\nNOTE: This method will not include cancelled people.", "operationId": "Institution_getContactRows", "parameters": [ { "name": "instid", "in": "path", "description": "The ID of the institution.", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch for any people referred to by any\nof the contact rows.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The institution's contact rows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "institution.contactRows": { "type": "array", "items": { "$ref": "#/components/schemas/ContactRow" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/{instid}/get-attributes": { "get": { "tags": [ "institution" ], "summary": "Get one or more (possibly multi-valued) attributes of an institution.", "description": "Get one or more (possibly multi-valued) attributes of an institution.\nThe returned attributes are sorted by attribute scheme precedence and\nthen attribute precedence.", "operationId": "Institution_getAttributes", "parameters": [ { "name": "instid", "in": "path", "description": "The ID of the institution.", "required": true, "schema": { "type": "string" } }, { "name": "attrs", "in": "query", "description": "The attribute scheme(s) to fetch. This may\ninclude any number of the attributes or pseudo-attributes, but it\nmay not include references or attribute chains (see the documentation\nfor the `fetch` parameter in this class).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested attributes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/{instid}/members": { "get": { "tags": [ "institution" ], "summary": "Get all the members of the specified institution.", "description": "Get all the members of the specified institution.\n\nBy default, only a few basic details about each member are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of each person.\n\nNOTE: This method will not include cancelled people.", "operationId": "Institution_getMembers", "parameters": [ { "name": "instid", "in": "path", "description": "The ID of the institution.", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch for each person.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The institution'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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/inst/{instid}/{attrid}": { "get": { "tags": [ "institution" ], "summary": "Get a specific attribute of an institution.", "description": "Get a specific attribute of an institution.", "operationId": "Institution_getAttribute", "parameters": [ { "name": "instid", "in": "path", "description": "The ID of the institution.", "required": true, "schema": { "type": "string" } }, { "name": "attrid", "in": "path", "description": "The ID of the attribute to fetch.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The requested attribute.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "attribute": { "$ref": "#/components/schemas/Attribute" } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/last-transaction": { "get": { "tags": [ "ibis" ], "summary": "Get the ID of the last (most recent) transaction.", "description": "Get the ID of the last (most recent) transaction.\n\nA transaction represents an edit made to data in Lookup. Each\ntransaction is assigned a unique, sequential, numeric ID. Thus\nthis last transaction ID will increase each time some data in\nLookup is changed.", "operationId": "Ibis_getLastTransactionId", "responses": { "200": { "description": "The ID of the latest transaction.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "value": { "type": "integer", "format": "int64" } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/all-attr-schemes": { "get": { "tags": [ "person" ], "summary": "Return a list of all the person attribute schemes available.", "description": "Return a list of all the person attribute schemes available. The\n`schemeid` values of these schemes may be used in the\n`fetch` parameter of other methods that return people.\n\nNOTE: Some of these attribute schemes are not currently used (no\npeople have attribute values in the scheme). These schemes are\nreserved for possible future use.", "operationId": "Person_allAttributeSchemes", "responses": { "200": { "description": "All the available person attribute schemes (in precedence\norder).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "attributeSchemes": { "type": "array", "items": { "$ref": "#/components/schemas/AttributeScheme" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/all-people": { "get": { "tags": [ "person" ], "summary": "Return a list of all people (in batches).", "description": "Return a list of all people (in batches).\n\nThe results are sorted by identifier, starting with the first person\nafter the person with the specified identifier. Thus, to iterate over\nall people, pass a `null` identifier to get the first batch of\npeople, then pass the last identifier from the previous batch to get\nthe next batch, and repeat until no more people are returned.\n\nBy default, only a few basic details about each person are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references.", "operationId": "Person_allPeople", "parameters": [ { "name": "includeCancelled", "in": "query", "description": "Flag to allow cancelled people to\nbe included (people who are no longer members of the University).\nDefaults to `false`.", "required": false, "schema": { "type": "boolean" } }, { "name": "identifier", "in": "query", "description": "The identifier (CRSid) of the person to\nstart after, or `null` to start from the first person.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "The maximum number of people to return.\nDefaults to 100.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested people (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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/list": { "get": { "tags": [ "person" ], "summary": "Get the people with the specified identifiers (typically CRSids).", "description": "Get the people with the specified identifiers (typically CRSids).\n\nEach identifier may be either a CRSid, or an identifier from another\nidentifier scheme, prefixed with that scheme's name and a slash. For\nexample `\"mug99\"` or `\"usn/123456789\"`.\n\nBy default, only a few basic details about each person are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references.\n\nThe results are sorted by identifier scheme and value.\n\nNOTE: The number of people that may be fetched in a single call is\nlimited by the URL path length limit (around 8000 characters). A\nCRSid is up to 7 characters long, and other identifiers are typically\nlonger, since they must also include the identifier scheme. Thus the\nnumber of people that this method may fetch is typically limited to a\nfew hundred.\n\nNOTE: The people returned may include cancelled people. It is the\ncaller's repsonsibility to check their cancelled flags.", "operationId": "Person_listPeople", "parameters": [ { "name": "crsids", "in": "query", "description": "A comma-separated list of identifiers. The name\nof the query parameter reflects a time when only crsids were used with\nlookup. Alternate schemes can be specified as noted above.", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested people (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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/modified-people": { "get": { "tags": [ "person" ], "summary": "Find all people modified between the specified pair of transactions.", "description": "Find all people modified between the specified pair of transactions.\n\nThe transaction IDs specified should be the IDs from two different\nrequests for the last (most recent) transaction ID, made at different\ntimes, that returned different values, indicating that some Lookup\ndata was modified in the period between the two requests. This method\nthen determines which (if any) people were affected.\n\nBy default, only a few basic details about each person are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references.\n\nNOTE: All data returned reflects the latest available data about each\nperson. It is not possible to query for old data, or more detailed\ninformation about the specific changes made.", "operationId": "Person_modifiedPeople", "parameters": [ { "name": "minTxId", "in": "query", "description": "Include modifications made in transactions\nafter (but not including) this one.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "maxTxId", "in": "query", "description": "Include modifications made in transactions\nup to and including this one.", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "crsids", "in": "query", "description": "Only include people with identifiers in this\nlist. By default, all modified people will be included.", "required": false, "schema": { "type": "string" } }, { "name": "includeCancelled", "in": "query", "description": "Include cancelled people (people\nwho are no longer members of the University). By default, cancelled\npeople are excluded.", "required": false, "schema": { "type": "boolean" } }, { "name": "membershipChanges", "in": "query", "description": "Include people whose group or\ninstitutional memberships have changed. By default, only people whose\nattributes have been directly modified are included.", "required": false, "schema": { "type": "boolean" } }, { "name": "instNameChanges", "in": "query", "description": "Include people who are members of\ninstituions whose names have changed. This will also cause people\nwhose group or institutional memberships have changed to be included.\nBy default, changes to institution names do not propagate to people.", "required": false, "schema": { "type": "boolean" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The modified people (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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/search": { "get": { "tags": [ "person" ], "summary": "Search for people using a free text query string.", "description": "Search for people using a free text query string. This is the same\nsearch function that is used in the Lookup web application.\n\nBy default, only a few basic details about each person are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references.\n\nNOTE: If the query string starts with the prefix `\"person:\"`, it\nis treated as an [LQL query](/lql), allowing\nmore advanced searches. An LQL query will ignore the\n`approxMatches` and `attributes` parameters, but\nit will respect the values of `includeCancelled` and\n`misStatus`. In addition, an LQL query will ignore the\n`orderBy` parameter, since LQL queries always return\nresults in ID order.", "operationId": "Person_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\nmatching in the search, causing more results to be returned. Defaults\nto `false`. This is ignored for LQL queries.", "required": false, "schema": { "type": "boolean" } }, { "name": "includeCancelled", "in": "query", "description": "Flag to allow cancelled people to\nbe included (people who are no longer members of the University).\nDefaults to `false`.", "required": false, "schema": { "type": "boolean" } }, { "name": "misStatus", "in": "query", "description": "The type of people to search for. This may\nbe\n\n* `\"staff\"` - only include people whose MIS status is\n `\"\"` (empty string), `\"staff\"`, or\n `\"staff,student\"`.\n\n* `\"student\"` - only include people whose MIS status is set to\n `\"student\"` or `\"staff,student\"`.\n\nOtherwise all matching people will be included (the default). Note\nthat the `\"staff\"` and `\"student\"` options are not\nmutually exclusive.", "required": false, "schema": { "type": "string" } }, { "name": "attributes", "in": "query", "description": "A comma-separated list of attributes to\nconsider when searching. If this is `null` (the default) then\nall attribute schemes marked as searchable will be included. This is\nignored for LQL queries.", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "description": "The number of results to skip at the start\nof the search. Defaults to 0.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "The maximum number of results to return.\nDefaults to 100.", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "orderBy", "in": "query", "description": "The order in which to list the results.\nThis may be either `\"identifier\"` or `\"surname\"` (the\ndefault for non-LQL queries). This is ignored for LQL queries, which\nalways return results in identifier order.", "required": false, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The matching people.", "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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/search-count": { "get": { "tags": [ "person" ], "summary": "Count the number of people that would be returned by a search using\na free text query string.", "description": "Count the number of people that would be returned by a search using\na free text query string.\n\nNOTE: If the query string starts with the prefix `\"person:\"`, it\nis treated as an [LQL query](/lql), allowing\nmore advanced searches. An LQL query will ignore the\n`approxMatches` and `attributes` parameters, but\nit will respect the values of `includeCancelled` and\n`misStatus`.", "operationId": "Person_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\nmatching in the search, causing more results to be returned. Defaults\nto `false`. This is ignored for LQL queries.", "required": false, "schema": { "type": "boolean" } }, { "name": "includeCancelled", "in": "query", "description": "Flag to allow cancelled people to\nbe included (people who are no longer members of the University).\nDefaults to `false`.", "required": false, "schema": { "type": "boolean" } }, { "name": "misStatus", "in": "query", "description": "The type of people to search for. This may\nbe\n\n* `\"staff\"` - only include people whose MIS status is\n `\"\"` (empty string), `\"staff\"`, or\n `\"staff,student\"`.\n\n* `\"student\"` - only include people whose MIS status is set to\n `\"student\"` or `\"staff,student\"`.\n\nOtherwise all matching people will be included (the default). Note\nthat the `\"staff\"` and `\"student\"` options are not\nmutually exclusive.", "required": false, "schema": { "type": "string" } }, { "name": "attributes", "in": "query", "description": "A comma-separated list of attributes to\nconsider when searching. If this is `null` (the default) then\nall attribute schemes marked as searchable will be included. This is\nignored for LQL queries.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The number of matching people.", "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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}": { "get": { "tags": [ "person" ], "summary": "Get the person with the specified identifier.", "description": "Get the person with the specified identifier.\n\nBy default, only a few basic details about the person are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of the person.\n\nNOTE: The person returned may be a cancelled person. It is the\ncaller's repsonsibility to check its cancelled flag.", "operationId": "Person_getPerson", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes\nsuch as `\"usn\"` or `\"staffNumber\"` may be available.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person to fetch\n(typically their CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested person or `null` if they were not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/Person" } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}/get-attributes": { "get": { "tags": [ "person" ], "summary": "Get one or more (possibly multi-valued) attributes of a person.", "description": "Get one or more (possibly multi-valued) attributes of a person. The\nreturned attributes are sorted by attribute scheme precedence and\nthen attribute precedence.", "operationId": "Person_getAttributes", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes may be\navailable in the future, such as `\"usn\"` or\n`\"staffNumber\"`.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person (typically\ntheir CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "attrs", "in": "query", "description": "The attribute scheme(s) to fetch. This may\ninclude any number of the attributes or pseudo-attributes, but it\nmay not include references or attribute chains (see the documentation\nfor the `fetch` parameter in this class).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The requested attributes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}/groups": { "get": { "tags": [ "person" ], "summary": "Get all the groups to which the specified person belongs, including\nindirect group memberships, via groups that include other groups.", "description": "Get all the groups to which the specified person belongs, including\nindirect group memberships, via groups that include other groups.\nThe returned list of groups is sorted by groupid.\n\nNote that some group memberships may not be visible to you. This\nmethod will only return those group memberships that you have\npermission to see.\n\nBy default, only a few basic details about each group are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of each group.\n\nNOTE: This method will not include cancelled groups.", "operationId": "Person_getGroups", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes may be\navailable in the future, such as `\"usn\"` or\n`\"staffNumber\"`.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person (typically\ntheir CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The person's 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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}/insts": { "get": { "tags": [ "person" ], "summary": "Get all the institutions to which the specified person belongs.", "description": "Get all the institutions to which the specified person belongs. The\nreturned list of institutions is sorted by name.\n\nBy default, only a few basic details about each institution are\nreturned, but the optional `fetch` parameter may be used\nto fetch additional attributes or references of each institution.\n\nNOTE: This method will not include cancelled institutions.", "operationId": "Person_getInsts", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes may be\navailable in the future, such as `\"usn\"` or\n`\"staffNumber\"`.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person (typically\ntheir CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The person's institutions (in name order).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}/is-member-of-group/{groupid}": { "get": { "tags": [ "person" ], "summary": "Test if the specified person is a member of the specified group.", "description": "Test if the specified person is a member of the specified group.\n\nNOTE: This may be used with cancelled people and groups.", "operationId": "Person_isMemberOfGroup", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes may be\navailable in the future, such as `\"usn\"` or\n`\"staffNumber\"`.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person (typically\ntheir CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "groupid", "in": "path", "description": "The ID or name of the group.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`true` if the specified person is in the specified\ngroup, `false` otherwise (or if the person or group does not\nexist).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "value": { "type": "boolean" } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}/is-member-of-inst/{instid}": { "get": { "tags": [ "person" ], "summary": "Test if the specified person is a member of the specified institution.", "description": "Test if the specified person is a member of the specified institution.\n\nNOTE: This may be used with cancelled people and institutions, but\nit will not include cancelled membership groups.", "operationId": "Person_isMemberOfInst", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes may be\navailable in the future, such as `\"usn\"` or\n`\"staffNumber\"`.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person (typically\ntheir CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "instid", "in": "path", "description": "The ID of the institution.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`true` if the specified person is in the specified\ninstitution, `false` otherwise (or if the person or institution\ndoes not exist).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "value": { "type": "boolean" } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}/manages-groups": { "get": { "tags": [ "person" ], "summary": "Get all the groups that the specified person has persmission to edit.", "description": "Get all the groups that the specified person has persmission to edit.\nThe returned list of groups is sorted by groupid.\n\nNote that some group memberships may not be visible to you. This\nmethod will only include groups for which you have persmission to\nsee the applicable manager group memberships.\n\nBy default, only a few basic details about each group are returned,\nbut the optional `fetch` parameter may be used to fetch\nadditional attributes or references of each group.\n\nNOTE: This method will not include cancelled groups.", "operationId": "Person_getManagedGroups", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes may be\navailable in the future, such as `\"usn\"` or\n`\"staffNumber\"`.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person (typically\ntheir CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The groups that the person manages (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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}/manages-insts": { "get": { "tags": [ "person" ], "summary": "Get all the institutions that the specified person has permission to\nedit.", "description": "Get all the institutions that the specified person has permission to\nedit. The returned list of institutions is sorted by name.\n\nNote that some group memberships may not be visible to you. This\nmethod will only include institutions for which you have permission\nto see the applicable editor group memberships.\n\nBy default, only a few basic details about each institution are\nreturned, but the optional `fetch` parameter may be used\nto fetch additional attributes or references of each institution.\n\nNOTE: This method will not include cancelled institutions.", "operationId": "Person_getManagedInsts", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes may be\navailable in the future, such as `\"usn\"` or\n`\"staffNumber\"`.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person (typically\ntheir CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "fetch", "in": "query", "description": "A comma-separated list of any additional\nattributes or references to fetch.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The institutions that the person manages (in name order).", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" } } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/person/{scheme}/{identifier}/{attrid}": { "get": { "tags": [ "person" ], "summary": "Get a specific attribute of a person.", "description": "Get a specific attribute of a person.", "operationId": "Person_getAttribute", "parameters": [ { "name": "scheme", "in": "path", "description": "The person identifier scheme. Typically this\nshould be `\"crsid\"`, but other identifier schemes may be\navailable in the future, such as `\"usn\"` or\n`\"staffNumber\"`.", "required": true, "schema": { "type": "string" } }, { "name": "identifier", "in": "path", "description": "The identifier of the person (typically\ntheir CRSid).", "required": true, "schema": { "type": "string" } }, { "name": "attrid", "in": "path", "description": "The ID of the attribute to fetch.", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "The requested attribute.", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "attribute": { "$ref": "#/components/schemas/Attribute" } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } }, "/version": { "get": { "tags": [ "ibis" ], "summary": "Get the current API version number.", "description": "Get the current API version number.", "operationId": "Ibis_getVersion", "responses": { "200": { "description": "The API version number string.", "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.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } }, "default": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "schemas": { "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\nis associated with. This will not be set for institution attributes." }, "visibility": { "type": "string", "description": "For a person attribute, it's visibility (`\"private\"`,\n`\"institution\"`, `\"university\"` or `\"world\"`). This\nwill 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\nthe user agent group that created it)." } }, "description": "Class representing an attribute of a person or institution returned by\nthe web service API. Note that for institution attributes, the instid,\nvisibility and owningGroupid fields will be `null`." }, "AttributeScheme": { "type": "object", "properties": { "schemeid": { "type": "string", "description": "The unique identifier of the attribute scheme." }, "precedence": { "type": "integer", "format": "int32", "description": "The attribute scheme's precedence. Methods that return or display\nattributes sort the results primarily in order of increasing values\nof attribute scheme precedence." }, "ldapName": { "type": "string", "description": "The name of the attribute scheme in LDAP, if it is exported to LDAP.\nNote that many attributes are not exported to LDAP, in which case\nthis name is typically just equal to the scheme's ID." }, "displayName": { "type": "string", "description": "The display name for labelling attributes in this scheme." }, "dataType": { "type": "string", "description": "The attribute scheme's datatype." }, "multiValued": { "type": "boolean", "description": "Flag indicating whether attributes in this scheme can be multi-valued." }, "multiLined": { "type": "boolean", "description": "Flag for textual attributes schemes indicating whether they are\nmulti-lined." }, "searchable": { "type": "boolean", "description": "Flag indicating whether attributes of this scheme are searched by\nthe default search functionality." }, "regexp": { "type": "string", "description": "For textual attributes, an optional regular expression that all\nattributes in this scheme match." } }, "description": "Class representing an attribute scheme. This may apply to attributes of\npeople or institutions." }, "ContactPhoneNumber": { "type": "object", "properties": { "phoneType": { "type": "string", "description": "The phone number's type." }, "number": { "type": "string", "description": "The phone number." }, "comment": { "type": "string", "description": "Any comment associated with the phone number." } }, "description": "Class representing a phone number held on an institution contact row, for\nuse 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\nbold." }, "italic": { "type": "boolean", "description": "Flag indicating if the contact row's text is normally displayed in\nitalics." }, "addresses": { "type": "array", "items": { "type": "string" }, "description": "A list of the contact row's addresses. This will always be non-null,\nbut 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\nnon-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\nbe 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\nnon-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,\nbut may be an empty list." } }, "description": "Class representing an institution contact row, for use by the web\nservices API." }, "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,\nfor use by the web service 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." }, "Group": { "type": "object", "properties": { "cancelled": { "type": "boolean", "description": "Flag indicating if the group is cancelled." }, "groupid": { "type": "string", "description": "The group's numeric ID (actually a string e.g., \"100656\")." }, "name": { "type": "string", "description": "The group's unique name (e.g., \"cs-editors\")." }, "title": { "type": "string", "description": "The group's title." }, "description": { "type": "string", "description": "The more detailed description of the group." }, "email": { "type": "string", "description": "The group's email address." }, "membersOfInst": { "allOf": [ { "$ref": "#/components/schemas/Institution" }, { "description": "The details of the institution for which this group forms all or\npart of the membership. This will only be set for groups that are\nmembership groups of institutions if the `fetch` parameter\nincludes the `\"members_of_inst\"` option." } ] }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/Person" }, "description": "A list of the group's members, including (recursively) any members of\nany included groups. This will only be populated if the\n`fetch` parameter includes the `\"all_members\"`\noption." }, "directMembers": { "type": "array", "items": { "$ref": "#/components/schemas/Person" }, "description": "A list of the group's direct members, not including any members\nincluded via groups included by this group. This will only be\npopulated if the `fetch` parameter includes the\n`\"direct_members\"` option." }, "owningInsts": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" }, "description": "A list of the institutions to which this group belongs. This will only\nbe populated if the `fetch` parameter includes the\n`\"owning_insts\"` option." }, "managesInsts": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" }, "description": "A list of the institutions managed by this group. This will only be\npopulated if the `fetch` parameter includes the\n`\"manages_insts\"` option." }, "managesGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of the groups managed by this group. This will only be\npopulated if the `fetch` parameter includes the\n`\"manages_groups\"` option." }, "managedByGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of the groups that manage this group. This will only be\npopulated if the `fetch` parameter includes the\n`\"managed_by_groups\"` option." }, "readsGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of the groups that this group has privileged access to. Members\nof this group will be able to read the members of any of those groups,\nregardless of the membership visibilities. This will only be populated\nif the `fetch` parameter includes the\n`\"reads_groups\"` option." }, "readByGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of the groups that have privileged access to this group.\nMembers of those groups will be able to read the members of this\ngroup, regardless of the membership visibilities. This will only be\npopulated if the `fetch` parameter includes the\n`\"read_by_groups\"` option." }, "includesGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of the groups directly included in this group. Any members of\nthe included groups (and recursively any groups that they include)\nwill automatically be included in this group. This will only be\npopulated if the `fetch` parameter includes the\n`\"includes_groups\"` option." }, "includedByGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of the groups that directly include this group. Any members of\nthis group will automatically be included in those groups (and\nrecursively in any groups that include those groups). This will only\nbe populated if the `fetch` parameter includes the\n`\"included_by_groups\"` option." }, "id": { "type": "string", "description": "An ID that can uniquely identify this group within the returned\nXML/JSON document. This is only used in the flattened XML/JSON\nrepresentation (if the \"flatten\" parameter is specified)." }, "ref": { "type": "string", "description": "A reference (by id) to a group element in the XML/JSON document.\nThis is only used in the flattened XML/JSON representation (if the\n\"flatten\" parameter is specified)." } }, "description": "Class representing a group returned by the web service API." }, "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." }, "Institution": { "type": "object", "properties": { "cancelled": { "type": "boolean", "description": "Flag indicating if the institution is cancelled." }, "instid": { "type": "string", "description": "The institution's unique ID (e.g., \"CS\")." }, "name": { "type": "string", "description": "The institution's name." }, "acronym": { "type": "string", "description": "The institution's acronym, if set (e.g., \"UCS\")." }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" }, "description": "A list of the institution's attributes. This will only be populated\nif the `fetch` parameter includes the `\"all_attrs\"`\noption, or any specific attribute schemes such as `\"email\"` or\n`\"address\"`, or the special pseudo-attribute scheme\n`\"phone_numbers\"`." }, "contactRows": { "type": "array", "items": { "$ref": "#/components/schemas/ContactRow" }, "description": "A list of the institution's contact rows. This will only be populated\nif the `fetch` parameter includes the\n`\"contact_rows\"` option." }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/Person" }, "description": "A list of the institution's members. This will only be populated if\nthe `fetch` parameter includes the `\"all_members\"`\noption." }, "parentInsts": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" }, "description": "A list of the institution's parent institutions. This will only be\npopulated if the `fetch` parameter includes the\n`\"parent_insts\"` option.\n\nNOTE: Currently all institutions have one parent, but in the future\ninstitutions may have multiple parents." }, "childInsts": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" }, "description": "A list of the institution's child institutions. This will only be\npopulated if the `fetch` parameter includes the\n`\"child_insts\"` option." }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of all the groups that belong to the institution. This will\nonly be populated if the `fetch` parameter includes the\n`\"inst_groups\"` option." }, "membersGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of the groups that form the institution's membership. This\nwill only be populated if the `fetch` parameter includes\nthe `\"members_groups\"` option." }, "managedByGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of the groups that manage this institution. This will only\nbe populated if the `fetch` parameter includes the\n`\"managed_by_groups\"` option." }, "id": { "type": "string", "description": "An ID that can uniquely identify this institution within the\nreturned XML/JSON document. This is only used in the flattened\nXML/JSON representation (if the \"flatten\" parameter is specified)." }, "ref": { "type": "string", "description": "A reference (by id) to an institution element in the XML/JSON\ndocument. This is only used in the flattened XML/JSON representation\n(if the \"flatten\" parameter is specified)." } }, "description": "Class representing an institution returned 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 their CRSid)." } ] }, "displayName": { "type": "string", "description": "The person's display name (if visible)." }, "registeredName": { "type": "string", "description": "The person's registered name (if visible)." }, "surname": { "type": "string", "description": "The person's surname (if visible)." }, "visibleName": { "type": "string", "description": "The person's display name if that is visible, otherwise their\nregistered name if that is visible, otherwise their surname if\nthat is visible, otherwise the value of their primary identifier\n(typically their CRSid) which is always visible." }, "misAffiliation": { "type": "string", "description": "The person's MIS status (`\"staff\"`, `\"student\"`,\n`\"staff,student\"` or `\"\"`)." }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/Identifier" }, "description": "A list of the person's identifiers. This will only be populated if\nthe `fetch` parameter included the\n`\"all_identifiers\"` option." }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" }, "description": "A list of the person's attributes. This will only be populated if the\n`fetch` parameter includes the `\"all_attrs\"` option,\nor any specific attribute schemes such as `\"email\"` or\n`\"title\"`, or the special pseudo-attribute scheme\n`\"phone_numbers\"`." }, "institutions": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" }, "description": "A list of all the institution's to which the person belongs. This\nwill only be populated if the `fetch` parameter includes\nthe `\"all_insts\"` option." }, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of all the groups to which the person belongs, including\nindirect group memberships, via groups that include other groups.\nThis will only be populated if the `fetch` parameter\nincludes the `\"all_groups\"` option." }, "directGroups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "A list of all the groups that the person directly belongs to. This\ndoes not include indirect group memberships - i.e., groups that\ninclude these groups. This will only be populated if the\n`fetch` parameter includes the `\"direct_groups\"`\noption." }, "id": { "type": "string", "description": "An ID that can uniquely identify this person within the returned\nXML/JSON document. This is only used in the flattened XML/JSON\nrepresentation (if the \"flatten\" parameter is specified)." }, "ref": { "type": "string", "description": "A reference (by id) to a person element in the XML/JSON document.\nThis is only used in the flattened XML/JSON representation (if the\n\"flatten\" parameter is specified)." } }, "description": "Class representing a person returned by the web service API. Note that\nthe identifier is the person's primary identifier (typically their CRSid),\nregardless of which identifier was used to query for the person." } }, "responses": { "ServerError": { "description": "Unexpected error", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Error" } }, "description": "Class representing the top-level container for all XML and JSON results.\nThis may be just a simple textual value or it may contain more complex\nentities such as people, institutions, groups, attributes, etc." } } } } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } }, "security": [ { "basicAuth": [ ] } ], "tags": [ { "name": "ibis", "description": "Common methods for searching for objects in the Lookup/Ibis database." }, { "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`." }, { "name": "institution", "description": "Methods for querying and manipulating institutions.\n\n#### The fetch parameter for institutions\n\nAll methods that return institutions also accept an optional\n`fetch` parameter that may be used to request additional\ninformation about the institutions returned. For more details about\nthe general rules that apply to the `fetch` parameter,\nrefer to the `PersonMethods` documentation.\n\nFor institutions the `fetch` parameter may be used to fetch\nany institution attribute by specifying the `schemeid` of an\ninstitution attribute scheme. Examples include `\"address\"`,\n`\"jpegPhoto\"`, `\"universityPhone\"`, `\"instPhone\"`,\n`\"landlinePhone\"`, `\"mobilePhone\"`, `\"faxNumber\"`,\n`\"email\"` and `\"labeledURI\"`. The full list (which may be\nextended over time) may be obtained using `#allAttributeSchemes`.\n\nIn addition the following pseudo-attributes are supported:\n\n* `\"phone_numbers\"` - fetches all phone numbers. This is\n equivalent to\n `\"universityPhone,instPhone,landlinePhone,mobilePhone\"`.\n\n* `\"all_attrs\"` - fetches all attributes from all institution\n attribute schemes. This does not include references.\n\n* `\"contact_rows\"` - fetches all institution contact rows. Any\n chained fetches from contact rows are used to fetch attributes from any\n people referred to by the contact rows.\n\nThe `fetch` parameter may also be used to fetch referenced\npeople, institutions or groups. This will only include references to\nnon-cancelled entities. The following references are supported:\n\n* `\"all_members\"` - fetches all the people who are members of the\n institution.\n\n* `\"parent_insts\"` - fetches all the parent institutions. Note\n that currently all institutions have only one parent, but this may change\n in the future, and client applications should be prepared to handle\n multiple parents.\n\n* `\"child_insts\"` - fetches all the child institutions.\n\n* `\"inst_groups\"` - fetches all the groups that belong to the\n institution.\n\n* `\"members_groups\"` - fetches all the groups that form the\n institution's membership list.\n\n* `\"managed_by_groups\"` - fetches all the groups that manage the\n institution's data (commonly called \"Editor\" groups).\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 institution. For more information about what can be fetched from\nreferenced people and groups, refer to the documentation for\n`PersonMethods` and `GroupMethods`." }, { "name": "person", "description": "Methods for querying and manipulating people.\n\n#### Notes on the fetch parameter\n\nAll methods that return people, institutions or groups also accept an\noptional `fetch` parameter that may be used to request\nadditional information about the entities returned. Without this\nparameter, only a few basic details about each person, institution or\ngroup are returned. The `fetch` parameter is quite flexible,\nand may be used in a number of different ways:\n\n* **Attribute fetching**. Attributes may be fetched by specifying the\n `schemeid` of an attribute scheme. For example to fetch a\n person's email addresses, use the value `\"email\"`. For people common\n attribute schemes include `\"jpegPhoto\"`, `\"misAffiliation\"`,\n `\"title\"`, `\"universityPhone\"`, `\"landlinePhone\"`,\n `\"mobilePhone\"`, `\"pager\"`, `\"labeledURI\"` and `\"address\"`.\n The full list of person attribute schemes may be obtained using `#allAttributeSchemes`.\n\n* **Pseudo-attributes**. Certain special pseudo-attributes are defined\n for convenience. For people, the following pseudo-attributes are supported:\n\n * `\"phone_numbers\"` - fetches all phone numbers. This is\n equivalent to\n `\"universityPhone,instPhone,landlinePhone,mobilePhone,pager\"`.\n\n * `\"all_identifiers\"` - fetches all identifiers. Currently people\n only have CRSid identifiers, but in the future additional identifiers such\n as USN or staffNumber may be added.\n\n * `\"all_attrs\"` - fetches all attributes from all person attribute\n schemes. This does not include identifiers or references.\n\n* **Reference fetching**. For people, the following references are\n supported (and will fetch only non-cancelled institutions and groups):\n\n * `\"all_insts\"` - fetches all the institutions to which the person\n belongs (sorted in name order).\n\n * `\"all_groups\"` - fetches all the groups that the person is a\n member of, including indirect group memberships, via groups that include\n other groups.\n\n * `\"direct_groups\"` - fetches all the groups that the person is\n directly a member of. This does not include indirect group memberships -\n i.e., groups that include these groups.\n\n* **Chained reference fetching**. To fetch properties of referenced\n objects, the \"dot\" notation may be used. For example, to fetch the email\n addresses of all the institutions to which a person belongs, use\n `\"all_insts.email\"`. Chains may include a number of reference\n following steps, for example\n `\"all_insts.managed_by_groups.all_members.email\"` will fetch all the\n institutions to which the person belongs, all the groups that manage those\n institutions, all the visible members of those groups and all the email\n addresses of those managing group members. For more information about what\n can be fetched from referenced institutions and groups, refer to the\n documentation for `InstitutionMethods` and `GroupMethods`.\n\nMultiple values of the `fetch` parameter should be separated\nby commas.\n\n#### Fetch parameter examples\n\n`fetch = \"email\"`\nThis fetches all the person's email addresses.\n\n`fetch = \"title,address\"`\nThis fetches all the person's titles (roles) and addresses.\n\n`fetch = \"all_attrs\"`\nThis fetches all the person's attributes.\n\n`fetch = \"all_groups,all_insts\"`\nThis fetches all the groups and institutions to which the person belongs.\n\n`fetch = \"all_insts.parent_insts\"`\nThis fetches all the person's institutions, and their parent institutions.\n\n`fetch = \"all_insts.email,all_insts.all_members.email\"`\nThis fetches all the person's institutions and their email addresses, and\nall the members of those institutions, and the email addresses of all\nthose members." } ], "externalDocs": { "description": "More information", "url": "https://www.lookup.cam.ac.uk/doc/ws-doc" } }