CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.12] - 2022-09-27
+
+### Changed
+
+- Fixed default base URLs for student and staff APIs
+- Switched to 'python-prior' generator to maintain compatibility following v6.2.0 update
+
+## [1.0.11] - 2022-09-06
+
+### Changed
+
+- Refresh OpenAPI spec.
+
 ## [1.0.10] - 2022-08-23
 
 ### Added

Dockerfile

@@ -5,39 +5,42 @@ FROM openapitools/openapi-generator-cli as builder
 
 WORKDIR /generated
 
+# openapi-generator-cli v6.2.0 changed the python generator. Using 'python-prior' until we have
+# checked the impact of this change
+
 RUN docker-entrypoint.sh generate \
     --input-spec https://developer.api.apps.cam.ac.uk/portals/api/sites/api-prod-a3dc87f7-prod/liveportal/apis/card/download_spec \
-    --generator-name python \
+    --generator-name python-prior \
     --additional-properties packageName=identitylib.card_client \
     --output /generated
 
 RUN docker-entrypoint.sh generate \
     --input-spec https://developer.api.apps.cam.ac.uk/portals/api/sites/api-prod-a3dc87f7-prod/liveportal/apis/university-human-resources/download_spec \
-    --generator-name python \
+    --generator-name python-prior \
     --additional-properties packageName=identitylib.hr_client \
     --output /generated
 
 RUN docker-entrypoint.sh generate \
     --input-spec https://developer.api.apps.cam.ac.uk/portals/api/sites/api-prod-a3dc87f7-prod/liveportal/apis/lookup/download_spec \
-    --generator-name python \
+    --generator-name python-prior \
     --additional-properties packageName=identitylib.lookup_client \
     --output /generated
 
 RUN docker-entrypoint.sh generate \
     --input-spec https://developer.api.apps.cam.ac.uk/portals/api/sites/api-prod-a3dc87f7-prod/liveportal/apis/photo/download_spec \
-    --generator-name python \
+    --generator-name python-prior \
     --additional-properties packageName=identitylib.photo_client \
     --output /generated
 
 RUN docker-entrypoint.sh generate \
     --input-spec https://developer.api.apps.cam.ac.uk/portals/api/sites/api-prod-a3dc87f7-prod/liveportal/apis/university-student/download_spec \
-    --generator-name python \
+    --generator-name python-prior \
     --additional-properties packageName=identitylib.student_client \
     --output /generated
 
 RUN docker-entrypoint.sh generate \
     --input-spec https://developer.api.apps.cam.ac.uk/portals/api/sites/api-prod-a3dc87f7-prod/liveportal/apis/inst-identifiers/download_spec \
-    --generator-name python \
+    --generator-name python-prior \
     --additional-properties packageName=identitylib.inst_identifier_client \
     --output /generated
 

README.md

@@ -44,6 +44,20 @@ $ ./test.sh -e py3 -- tests/test_identifiers.py
 $ ./test.sh -e py3 -- tests/test_identifiers.py -vvv
 ```
 
+### Pulling latest specs from source repositories
+
+Local copies of the OpenAPI specs used to generate the library should be pulled in to this repo
+so the specific specs used in each build are under revision control. This can be done using the
+provided script:
+
+```bash
+$ ./pull-specs.sh
+
+# If an access token required for https clones from gitlab repositories
+# then this can be specified using:
+$ ./pull-specs.sh --token "ACCESS_TOKEN_HERE"
+```
+
 ### Generating the identitylib
 
 The identitylib is generated during the docker build process. To create a local copy of the

identitylib/university_hr_configuration.py

@@ -9,7 +9,7 @@ class UniversityHRClientConfiguration(ClientCredentialsConfigurationMixin, Confi
         client_key,
         client_secret,
         access_token_url="https://api.apps.cam.ac.uk/oauth2/v1/token",
-        base_url="https://api.apps.cam.ac.uk/university-human-resources"
+        base_url="https://api.apps.cam.ac.uk/university-human-resources/v1alpha2"
     ):
 
         ClientCredentialsConfigurationMixin.__init__(

identitylib/university_student_configuration.py

@@ -9,7 +9,7 @@ class UniversityStudentClientConfiguration(ClientCredentialsConfigurationMixin,
         client_key,
         client_secret,
         access_token_url="https://api.apps.cam.ac.uk/oauth2/v1/token",
-        base_url="https://api.apps.cam.ac.uk/university-student"
+        base_url="https://api.apps.cam.ac.uk/university-student/v1alpha2"
     ):
 
         ClientCredentialsConfigurationMixin.__init__(

pull-specs.sh

+#!/usr/bin/env bash
+
+cd "${0%/*}"
+
+./scripts/pull-openapi-specs.py "$@"

scripts/pull-openapi-specs.py

+#!/usr/bin/env python3
+from typing import Optional
+import argparse
+import logging
+from pathlib import Path
+import yaml
+import tempfile
+from dataclasses import dataclass
+import git
+import os
+import shutil
+from urllib.parse import quote
+
+LOG = logging.getLogger(Path(__file__).stem)
+
+SPECS_FOLDER = 'specs'
+COMMIT_MESSAGE = 'Update OpenAPI specs'
+
+
+@dataclass
+class SpecConfig():
+    repo: str
+    branch: str
+    source: Optional[str] = 'openapi.yaml'
+    target: Optional[str] = None
+
+
+def load_config(source: str) -> dict[str, SpecConfig]:
+    LOG.info(f'Reading configuration from {source}')
+    with open(source) as fp:
+        sources = yaml.safe_load(fp)
+    spec_configs = {}
+    for name, c in sources.items():
+        spec = SpecConfig(**c)
+        if spec.target is None:
+            spec.target = os.path.join(SPECS_FOLDER, f'{name}.yaml')
+        spec_configs[name] = spec
+    return spec_configs
+
+
+def pull_specs(config: dict[str, SpecConfig], token: Optional[str]) -> set[str]:
+    spec_files = set()
+    for name, c in config.items():
+        LOG.info(f'{name}:')
+        repo = c.repo
+        if token:
+            # Token given so insert in to url, default to using USER env for username as
+            # this is needed for personal access tokens and ignored for project access tokens
+            creds = quote(os.getenv('USER', 'token')) + ':' + quote(token) + '@'
+            repo = repo.replace('https://', f'https://{creds}')
+        LOG.info(f"...cloning from {c.repo}{' (using token)' if token else ''} @ {c.branch}")
+        with tempfile.TemporaryDirectory() as tmp_dirname:
+            # Clone repo@branch in to temp directory without checkout then checkout
+            # just the file we want before copying it into this repo and recording
+            # the SHA of the last commit to affect it
+            repo = git.Repo.clone_from(
+                url=repo,
+                to_path=tmp_dirname,
+                branch=c.branch,
+                no_checkout=True,
+            )
+            LOG.info(f'...checking out {c.source}')
+            repo.git.checkout('HEAD', c.source)
+
+            LOG.info(f'...copying {c.source} to {c.target}')
+            shutil.copyfile(os.path.join(tmp_dirname, c.source), c.target)
+
+            last_commit = next(repo.iter_commits(paths=c.source, max_count=1))
+            commit_sha = 'Unknown' if last_commit is None else last_commit.hexsha
+            LOG.info(f'...sha of {c.source} is {commit_sha}')
+            sha_file = os.path.splitext(c.target)[0] + '.sha'
+            with open(sha_file, 'w') as fp:
+                fp.write(commit_sha)
+
+            spec_files.add(c.target)
+            spec_files.add(sha_file)
+
+    return spec_files
+
+
+def commit_specs(spec_files: set[str]):
+    this_repo_path = str(Path(__file__).parent.parent)  # Assume script is in subfolder in repo
+    LOG.info(f"Committing to repo {this_repo_path}")
+    repo = git.Repo(this_repo_path)
+    if str(repo.head.ref) in {'master', 'main'}:
+        LOG.error('...in master/main branch - aborting commit')
+    elif repo.index.diff('HEAD'):
+        LOG.error('...files already staged - aborting commit')
+    else:
+        LOG.info(f'...adding {", ".join(list(spec_files))}')
+        repo.index.add(spec_files)
+        changes = len(repo.index.diff('HEAD'))
+        if changes:
+            LOG.info(f'...{changes} files need committing')
+            repo.index.commit(COMMIT_MESSAGE)
+        else:
+            LOG.info('...no changes need committing')
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--configuration', '-c', type=str, default='sources.yaml')
+    parser.add_argument('--token', '-t', type=str)
+    parser.add_argument('--commit', action='store_true')
+    parser.add_argument('--debug', action='store_true')
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    logging.basicConfig(level=logging.DEBUG if args.debug else logging.INFO)
+    config = load_config(args.configuration)
+    spec_files = pull_specs(config, args.token)
+    if args.commit:
+        commit_specs(spec_files)

scripts/requirements.txt

+PyYAML
+GitPython

setup.py

@@ -8,7 +8,7 @@ PACKAGE_DESCRIPTION = (
     "A module containing helpers and shared code related to identity systems within UIS, "
     "University of Cambridge."
 )
-PACKAGE_VERSION = "1.0.10"
+PACKAGE_VERSION = "1.0.12"
 PACKAGE_URL = "https://gitlab.developers.cam.ac.uk/uis/devops/iam/identity-lib"
 
 

sources.yaml

+# Which OpenAPI specs to be pull from other repos by `pull-openapi-specs.py`
+#
+# Format:
+#   name:
+#     repo: repo url for git clone - required
+#     branch: git branch to use - required
+#     source: which file contains the spec in the repo - defaults to 'openapi.yaml'
+#     target: where to save pulled spec - defaults to 'specs/{name}.yaml'
+
+card:
+  repo: https://gitlab.developers.cam.ac.uk/uis/devops/iam/card-database/card-api
+  branch: master
+
+photo:
+  repo: https://gitlab.developers.cam.ac.uk/uis/devops/iam/identity-photos-service/photo-api
+  branch: master
+
+lookup:
+  repo: https://gitlab.developers.cam.ac.uk/uis/devops/iam/ibis/ibis
+  branch: master
+
+hr:
+  repo: https://gitlab.developers.cam.ac.uk/uis/devops/iam/staff-identity-api
+  branch: main
+
+student:
+  repo: https://gitlab.developers.cam.ac.uk/uis/devops/iam/student-api
+  branch: main
+
+inst_identifier:
+  repo: https://gitlab.developers.cam.ac.uk/uis/devops/iam/ibis/institution-mapping-tool
+  branch: master

specs/card.sha

+f1717dd0be8fd51396f2da896510f0d335099233
\ No newline at end of file

specs/hr.sha

+9e543ca652ef93c282084340bee24239394442c1
\ No newline at end of file

specs/hr.yaml

+openapi: 3.0.2
+info:
+  title: University Human Resources API
+  description: |2+
+    This API exposes identity information from the University Human Resources system.
+    The purpose of this API is to give access to basic identity information about staff
+    members for use by downstream systems, therefore the data exposed is limited to
+    basic information about who a staff member is and details of any affiliations they
+    have.
+
+    This API uses the following identifiers to link people to person-records held within
+    different systems:
+
+    * `person.v1.human-resources.university.identifiers.cam.ac.uk` - the university human resources (uhr) identifier of
+        this person - also known as the staff number of HRN.
+    * `v1.person.identifiers.cam.ac.uk` - the common registration scheme identifier (CRSid) of
+        this person.
+
+    Additionally this API uses the following identifiers to link people to institutions or
+    entities which a person may have an affiliation to:
+
+    * `institution.v1.human-resources.university.identifiers.cam.ac.uk` - the university human resources (uhr) institution
+        identifier. This encompasses departments within the University HR system
+        (currently CHRIS).
+    * `institution.v1.student-records.university.identifiers.cam.ac.uk` - the student records institution identifier. This
+        encompasses colleges within the University Student Records system (currently CamSIS).
+
+    Affiliations can be used to indicate an institution that a person holds a position within,
+    with the `status` indicating the job role that is held and the scheme of the affiliation being
+    `institution.v1.human-resources.university.identifiers.cam.ac.uk`. Additionally an affiliation can indicate a staff
+    member's line manager with the scheme being `person.v1.human-resources.university.identifiers.cam.ac.uk` and the
+    status being `report`. A staff member can have multiple institution affiliations and multiple
+    report affiliations.
+
+    This API is currently backed by data from CHRIS, exposing a view which is updated hourly.
+
+  version: v1alpha2
+servers:
+  - url: https://api.apps.cam.ac.uk/university-human-resources/v1alpha2
+    description: The production instance of the University Student API, published behind the API Gateway
+paths:
+  /staff:
+    get:
+      tags:
+        - Staff members
+      summary: List staff members
+      description: |2+
+
+        Lists all staff members held within the University Human Resources system, allowing basic
+        filtering by affiliation.
+
+        To avoid returning very large responses, this endpoint produces a paged response. Where
+        there are additional results which cannot be returned on a single page, a `next` field
+        will be populated with a url containing the next page of results. These `next` urls
+        should be followed until a page is returned with no `next` field, indicating that
+        there are no further results. The amount of results returned can be customized using
+        the `page_size` query parameter. The maximum amount of results returned is 999.
+
+        Staff members can be filtered by affiliation, by providing an `affiliation` query
+        parameter. This affiliation should be provided in the format `<value>@<scheme>`.
+
+      operationId: list_v1alpha2_staff_staff_get
+      parameters:
+        - description: An affiliation to filter by, in the format `<value>@<scheme>`. When included only the staff members with a matching affiliation are returned.
+          required: false
+          schema:
+            title: Affiliation
+            type: string
+            description: An affiliation to filter by, in the format `<value>@<scheme>`. When included only the staff members with a matching affiliation are returned.
+          example: CC@institution.v1.human-resources.university.identifiers.cam.ac.uk
+          name: affiliation
+          in: query
+        - description: The cursor indicating a unique page of results - this should be auto generated on the `next` and `previous` fields and does not need to be manually added / updated.
+          required: false
+          schema:
+            title: Cursor
+            type: string
+            description: The cursor indicating a unique page of results - this should be auto generated on the `next` and `previous` fields and does not need to be manually added / updated.
+          example: V2VsbCBhcmVuJ3QgeW91IGN1cmlvdXM=
+          name: cursor
+          in: query
+        - description: The number of results to return per page. This is limited to 999 results, if a number over 999 is provided the results will be capped at 999. Defaults to 200.
+          required: false
+          schema:
+            title: Page Size
+            type: integer
+            description: The number of results to return per page. This is limited to 999 results, if a number over 999 is provided the results will be capped at 999. Defaults to 200.
+          example: 500
+          name: page_size
+          in: query
+      responses:
+        "200":
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PaginatedResults_StaffMember_'
+        "400":
+          description: The request is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPException'
+        "422":
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
+  /staff/{identifier}:
+    get:
+      tags:
+        - Staff members
+      summary: Get a single staff member
+      description: |2+
+
+        Returns a single staff member based on the identifier provided. The identifier can be
+        provided in the format `<value>@<scheme>`, if the scheme is omitted it shall be
+        assumed that the scheme is `person.v1.human-resources.university.identifiers.cam.ac.uk` (also know as the staff number or HRN).
+
+        Currently this endpoint only supports querying by `person.v1.human-resources.university.identifiers.cam.ac.uk` and `v1.person.identifiers.cam.ac.uk`
+        identifiers.
+
+      operationId: get_v1alpha2_staff_member_staff__identifier__get
+      parameters:
+        - required: true
+          schema:
+            title: The identifier to query by
+            type: string
+          example: 10001@person.v1.human-resources.university.identifiers.cam.ac.uk
+          name: identifier
+          in: path
+      responses:
+        "200":
+          description: Successful Response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StaffMember'
+        "400":
+          description: The request is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPException'
+        "404":
+          description: The specified resource could not be found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPException'
+        "422":
+          description: Validation Error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPValidationError'
+components:
+  schemas:
+    Affiliation:
+      title: Affiliation
+      required:
+        - value
+        - status
+        - scheme
+      type: object
+      properties:
+        value:
+          title: Value
+          type: string
+          description: The value of this affiliation. This will be specific to the human resources system, indicating an entity that this staff member is affiliated with.
+        status:
+          title: Status
+          type: string
+          description: A staff member's status in relation to an affiliated entity. Currently this will be their job title or `report`, indicating that this person reports to the affiliated entity.
+        scheme:
+          $ref: '#/components/schemas/AffiliationScheme'
+        start:
+          title: Start
+          type: string
+          description: The start date of this affiliation. May not be populated if not known.
+          format: date
+        end:
+          title: End
+          type: string
+          description: The end date of this affiliation. May not be populated if the affiliation is open-ended.
+          format: date
+      description: |-
+        A representation of an affiliation - indicating what type of affiliation this is
+        and the entity which the affiliation is related to. Also contains a `status`
+        indicating the position of this staff member in relation to the affiliated entity.
+    AffiliationScheme:
+      title: AffiliationScheme
+      enum:
+        - institution.v1.human-resources.university.identifiers.cam.ac.uk
+        - institution.v1.student-records.university.identifiers.cam.ac.uk
+        - person.v1.human-resources.university.identifiers.cam.ac.uk
+      type: string
+      description: An enumeration.
+    HTTPException:
+      title: HTTPException
+      required:
+        - detail
+      type: object
+      properties:
+        detail:
+          title: Detail
+          type: string
+      description: |-
+        A representation of an error, detail about the cause of the error will be
+        provided on the `detail` field.
+      example:
+        detail: Detail will be given about the error which has occurred
+    HTTPValidationError:
+      title: HTTPValidationError
+      type: object
+      properties:
+        detail:
+          title: Detail
+          type: array
+          items:
+            $ref: '#/components/schemas/ValidationError'
+    Identifier:
+      title: Identifier
+      required:
+        - value
+        - scheme
+      type: object
+      properties:
+        value:
+          title: Value
+          type: string
+          description: The value of this identifier
+        scheme:
+          $ref: '#/components/schemas/IdentifierScheme'
+      description: A representation of a staff member's identifier.
+    IdentifierScheme:
+      title: IdentifierScheme
+      enum:
+        - person.v1.human-resources.university.identifiers.cam.ac.uk
+        - v1.person.identifiers.cam.ac.uk
+      type: string
+      description: An enumeration.
+    PaginatedResults_StaffMember_:
+      title: PaginatedResults[StaffMember]
+      required:
+        - results
+      type: object
+      properties:
+        next:
+          title: Next
+          type: string
+          description: The url to use to retrieve the next page of results.
+          example: https://api.example.com/widgets?cursor=V2VsbCBhcmV1IGN1cmlvdXM=
+        previous:
+          title: Previous
+          type: string
+          description: The url to use to retrieve the previous page of results.
+          example: https://api.example.com/widgets?cursor=5SFSDGcmlvdDFGXM=
+        results:
+          title: Results
+          type: array
+          items:
+            $ref: '#/components/schemas/StaffMember'
+          description: A list of the current page of results.
+    StaffMember:
+      title: StaffMember
+      required:
+        - identifiers
+        - namePrefixes
+        - surname
+        - forenames
+        - affiliations
+      type: object
+      properties:
+        identifiers:
+          title: Identifiers
+          type: array
+          items:
+            $ref: '#/components/schemas/Identifier'
+          description: The identifiers attached to this staff record.
+        namePrefixes:
+          title: Nameprefixes
+          type: string
+          description: The name prefixes of this member of staff, split by a single space.
+        surname:
+          title: Surname
+          type: string
+          description: The surname of this member of staff.
+        forenames:
+          title: Forenames
+          type: string
+          description: The forenames of this member of staff, split by a single space.
+        dateOfBirth:
+          title: Dateofbirth
+          type: string
+          description: The date of birth of this member of staff
+          format: date
+        affiliations:
+          title: Affiliations
+          type: array
+          items:
+            $ref: '#/components/schemas/Affiliation'
+          description: The list of entities that this staff member is affiliated with. Currently this includes college and department affiliations (under the scheme `institution.v1.human-resources.university.identifiers.cam.ac.uk`) as well as the staff member's line manager (if known), under the scheme `person.v1.human-resources.university.identifiers.cam.ac.uk`.
+      description: |-
+        A representation of a staff member - exposing the bare minimum information to identify a
+        member of staff and link them to affiliated institutions and people within the University.
+      example:
+        identifiers:
+          - scheme: person.v1.human-resources.university.identifiers.cam.ac.uk
+            value: "1000"
+        namePrefixes: MR
+        surname: Bloggs
+        forenames: John
+        dateOfBirth: "1992-01-01"
+        affiliations:
+          - scheme: institution.v1.human-resources.university.identifiers.cam.ac.uk
+            value: CC
+            status: Member
+            start: "2020-01-05"
+            end: "2030-01-03"
+          - scheme: institution.v1.human-resources.university.identifiers.cam.ac.uk
+            value: U100324
+            status: Research Fellow
+            start: "2021-02-15"
+    ValidationError:
+      title: ValidationError
+      required:
+        - loc
+        - msg
+        - type
+      type: object
+      properties:
+        loc:
+          title: Location
+          type: array
+          items:
+            anyOf:
+              - type: string
+              - type: integer
+        msg:
+          title: Message
+          type: string
+        type:
+          title: Error Type
+          type: string
+  securitySchemes:
+    ApiGatewayOAuthClientCredentials:
+      type: oauth2
+      description: Allows authentication using client credentials obtained from the API Gateway
+      flows:
+        clientCredentials:
+          tokenUrl: https://api.apps.cam.ac.uk/oauth/client_credential/accesstoken
+          scopes: {}
+security:
+  - ApiGatewayOAuthClientCredentials: []

specs/inst_identifier.sha

+e6914bce46874c0304acefb6dd107c24d47c4051
\ No newline at end of file

specs/inst_identifier.yaml

+openapi: "3.0.2"
+components:
+  responses:
+    MappingResponse:
+      content:
+        application/json:
+          examples:
+            Example:
+              value:
+                institutions:
+                - identifiers:
+                  - "AD@insts.lookup.cam.ac.uk"
+                  - "U00081@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+                  - "U10115@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+                  - "U10116@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+                  - "U10117@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+                  - "U10118@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+                  instid: "AD"
+                - identifiers:
+                  - "ADCTH@insts.lookup.cam.ac.uk"
+                  - "U00041@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+                  instid: "ADCTH"
+                - identifiers:
+                  - "AHTSTU@insts.lookup.cam.ac.uk"
+                  - "NUER@institution.v1.student.university.identifiers.cam.ac.uk"
+                  instid: "AHTSTU"
+          schema:
+            $ref: "#/components/schemas/MappingResponse"
+      description: "A mapping between Lookup institutions and other institutional\
+        \ identifiers."
+  schemas:
+    MappingDatum:
+      description: "A list of alternate identifiers for a Lookup instid."
+      example:
+        identifiers:
+        - "AD@insts.lookup.cam.ac.uk"
+        - "U00081@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+        - "U10115@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+        - "U10116@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+        - "U10117@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+        - "U10118@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+        instid: "AD"
+      properties:
+        identifiers:
+          description: "List of identifiers of this institution in various databases.\
+            \ Each identifier\nis of the form `{identifier}@{namespace}`."
+          example: "[\"AD@insts.lookup.cam.ac.uk\", \"U00081@institution.v1.human-resources.university.identifiers.cam.ac.uk\"\
+            ]"
+          items:
+            type: "string"
+          type: "array"
+        instid:
+          description: "Lookup instid for this institution."
+          example: "UIS"
+          type: "string"
+      required:
+      - "instid"
+      - "identifiers"
+      title: "Root Type for MappingDatum"
+      type: "object"
+    MappingResponse:
+      description: "A mapping from Lookup institutions to institutions in other databases."
+      example:
+        institutions:
+        - identifiers:
+          - "AD@insts.lookup.cam.ac.uk"
+          - "U00081@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+          - "U10115@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+          - "U10116@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+          - "U10117@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+          - "U10118@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+          instid: "AD"
+        - identifiers:
+          - "ADCTH@insts.lookup.cam.ac.uk"
+          - "U00041@institution.v1.human-resources.university.identifiers.cam.ac.uk"
+          instid: "ADCTH"
+        - identifiers:
+          - "AHTSTU@insts.lookup.cam.ac.uk"
+          - "NUER@institution.v1.student.university.identifiers.cam.ac.uk"
+          instid: "AHTSTU"
+      properties:
+        institutions:
+          description: "List of institution mapping data."
+          items:
+            $ref: "#/components/schemas/MappingDatum"
+          type: "array"
+      required:
+      - "institutions"
+      type: "object"
+  securitySchemes:
+    APIGatewayAuth:
+      description: "Authenticate using the API Gateway OAuth2 flows, requiring access\
+        \ to application credentials provisioned within the API Gateway."
+      flows:
+        authorizationCode:
+          authorizationUrl: "https://api.apps.cam.ac.uk/oauth2/v1/auth"
+          scopes:
+            https://api.apps.cam.ac.uk/institutions/mapping: "know what institutions\
+              \ are called in different University databases"
+          tokenUrl: "https://api.apps.cam.ac.uk/oauth2/v1/token"
+        clientCredentials:
+          scopes:
+            https://api.apps.cam.ac.uk/institutions/mapping: "know what institutions\
+              \ are called in different University databases"
+          tokenUrl: "https://api.apps.cam.ac.uk/oauth2/v1/token"
+      type: "oauth2"
+info:
+  contact:
+    email: "devops@uis.cam.ac.uk"
+    name: "UIS DevOps"
+    url: "https://guidebook.devops.uis.cam.ac.uk/en/latest/contact/"
+  description: "The Insitution Identifiers API provides a mapping between identifiers\
+    \ used\nin various University databases. The current known database namespaces\
+    \ are:\n\n* `insts.lookup.cam.ac.uk` - [Lookup](https://www.lookup.cam.ac.uk/)\
+    \ instids.\n* `institution.v1.human-resources.university.identifiers.cam.ac.uk`\
+    \ -\n  identifiers used in the Human Resources (HR) database.\n* `institution.v1.student.university.identifiers.cam.ac.uk`\
+    \ - identifiers used\n  in the Student Information System (SIS) database.\n\n\
+    The API provides a single endpoint which can be used to retrieve the\ncurrent\
+    \ reports as a JSON document. For example, on a machine with\n[curl](https://curl.se/)\
+    \ installed:\n\n```\n$ curl -o mapping.json https://api.apps.cam.ac.uk/institutions/mapping/v1\n\
+    ```\n\nThe API is useful if you need to reconcile records drawn from multiple\
+    \ databases\nand determine which institutions are equivalent between them."
+  title: "Institution Identifiers"
+  version: "1.0.0"
+paths:
+  /:
+    description: "The device statiscs endpoint represents the most recent report summarising\n\
+      unique visits recorded on raven.cam.ac.uk. Only the top 99.9% of devices are\n\
+      included in the reports with the remaining 0.1% being grouped together as\n\"\
+      other\"."
+    get:
+      description: "Retrieve the most recent institution mapping."
+      operationId: "getMapping"
+      responses:
+        "200":
+          $ref: "#/components/responses/MappingResponse"
+      security:
+      - APIGatewayAuth:
+        - "https://api.apps.cam.ac.uk/institutions/mapping"
+      summary: "Get latest mapping."
+    summary: "Latest device statistics reports."
+security:
+- APIGatewayAuth:
+  - "https://api.apps.cam.ac.uk/lookup"
+servers:
+- description: "Production instance"
+  url: "https://api.apps.cam.ac.uk/institutions/mapping/v1"

specs/lookup.sha

+66f461da6081372b2db0fc1450423b324f40d38d
\ No newline at end of file

specs/photo.sha

+c5b5c999fd53ab4f9dd32f9e474b1b241521e22d
\ No newline at end of file