openapi: 3.2.0
info:
  title: Tabula Jobs API
  version: v1
  summary: University of Warwick's teaching and learning administration API.
  description: 'Tabula is the University of Warwick''s system for the administration of teaching and learning. It is built and operated by the University''s own Information and Digital Group (IDG) / IT Services software engineering team — the iCal responses it emits carry `PRODID:-//Tabula//University of Warwick IT Services//EN`, and the source repositories sit under the institution''s own GitHub organisation. This is an institution-operated contract, not a vendor platform running under Warwick''s name.


    The API is resource-oriented, returns JSON in all responses including errors, and wraps every payload in a `success`/`status` envelope. A small number of calendar endpoints (term dates, term weeks, holiday dates) are fully public and require no credentials. Everything else is protected by Warwick Web Sign-on and requires either HTTP Basic Auth with an ITS External User account or an OAuth 1.0a token.


    Content negotiation: the calendar endpoints return JSON by default and iCalendar when the request carries `Accept: text/calendar` or the path ends in `.ics`.'
  termsOfService: https://warwick.ac.uk/terms/
  contact:
    name: University of Warwick ITS Web Team
    url: https://warwick.ac.uk/services/idg/services-support/web/tabula/api/
    email: webteam@warwick.ac.uk
  license:
    name: Warwick website terms of use
    url: https://warwick.ac.uk/terms/
servers:
- url: https://tabula.warwick.ac.uk/api/v1
  description: Production
- url: https://tabula-sandbox.warwick.ac.uk/api/v1
  description: Sandbox. Contains no staff data and only auto-generated fake student data. Access is granted on request to tabula@warwick.ac.uk.
security:
- {}
tags:
- name: Jobs
  description: Long-running asynchronous job instances.
paths:
  /job/{jobId}:
    get:
      tags:
      - Jobs
      operationId: retrieveJob
      summary: Retrieve a job instance
      description: Retrieve the status of a long-running asynchronous job.
      security:
      - basicAuth: []
      - oauth1: []
      parameters:
      - name: jobId
        in: path
        required: true
        description: The job instance identifier.
        schema:
          type: string
      responses:
        '200':
          description: The job instance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ErrorResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        required:
        - errors
        properties:
          success:
            const: false
          errors:
            type: array
            items:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
    JobResponse:
      allOf:
      - $ref: '#/components/schemas/Envelope'
      - type: object
        properties:
          job:
            type: object
            properties:
              id:
                type: string
              status:
                type: string
              succeeded:
                type: boolean
              progress:
                type: integer
    Envelope:
      type: object
      description: Every Tabula response carries this envelope.
      required:
      - success
      - status
      properties:
        success:
          type: boolean
        status:
          type: string
  responses:
    Unauthorized:
      description: HTTP authentication failed or was not supplied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: unauthorized
            errors:
            - message: API requests must be authenticated with HTTP Basic Auth or OAuth
    NotFound:
      description: The resource does not exist. Warwick documents that this can also occur when the request Content-Type is not application/json.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: not_found
            errors:
            - message: We don't know anything about this page
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication over HTTPS using a Warwick Web Sign-on ITS user code and password. Warwick documents that requests SHOULD use a dedicated External User account provisioned for API access.
    oauth1:
      type: apiKey
      in: header
      name: Authorization
      description: OAuth 1.0a. Warwick supports the RSA-SHA1 and HMAC-SHA1 signature algorithms and requires a Warwick-specific `scope` parameter naming the service being accessed. Request token, authorise and access token endpoints are on websignon.warwick.ac.uk. OpenAPI has no native OAuth 1.0a security scheme type, so this is expressed as the Authorization header it actually travels in.
externalDocs:
  description: Tabula API documentation
  url: https://warwick.ac.uk/services/idg/services-support/web/tabula/api/