openapi: 3.0.2
servers:
  - url: https://eo-data-bridge.ceda.ac.uk
info:
  description: This service provides data about the relationships between CCI and C3S datasets.
  title: CCI Data Bridge
  version: 0.0.1
tags:
  - name: dataset
    description: Get data about dataset relationships.
  - name: project
    description: Get information about projects.
  - name: relationtype
    description: Get information about relation types.
  - name: sankey
    description: Get a sanky diagram.

components:

  parameters:
    format_param:
      description: | 
        The response format.
        
        This will override any value of `Accept` in the request headers.
        Possible values are `html` and `json`. The default value is `html`.
      name: format
      in: query
      schema:
        type: string
        enum: 
          - html
          - json
        default: html
        example: html

    id:
      description: The id of a dataset/filter combination.
      name: id
      in: path
      required: true
      schema:
        type: integer
        minimum: 0
    sankey_format_param:
      description: | 
        The response format.
        
        This will override any value of `Accept` in the request headers.
        Possible values are `html`, `jpeg`, `png` and `svg`. The default value is `html`.
      name: format
      in: query
      schema:
        type: string
        enum: 
          - html
          - jpeg
          - png
          - svg
        default: html
        example: html

    project:
      description: |
        The name of a project
        
        Possible values are `cci`, `c3s` `cm` and `osi`. The default value is `cci`.
      name: project
      in: path
      required: true
      schema:
        type: string
        enum: 
          - cci
          - c3s
          - cm
          - osi
        default: cci
        example: cci

    url:
      description: The URL of a dataset.
      name: url
      in: path
      required: true
      schema:
        type: string

  responses:

    dataset_details:
      description: "OK"
      content:
        text/html:
          schema:
            $ref: "#/components/schemas/html"
        application/json:
          schema:
            $ref: "#/components/schemas/dataset"

    dataset_list:
      description: "OK"
      content:
        text/html:
          schema:
            $ref: "#/components/schemas/html"
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/dataset"

    project_list:
      description: "OK"
      content:
        text/html:
          schema:
            $ref: "#/components/schemas/html"
        application/json:
          schema:
            type: array
            items:
              description: Project name.
              type: string

    relationtype_list:
      description: "OK"
      content:
        text/html:
          schema:
            $ref: "#/components/schemas/html"
        application/json:
          schema:
            description: A list of relation types.
            type: array
            items:
              title: relation types
              type: object
              properties:
                name:
                  type: string
                description:
                  type: string

    error_message:
      description: The provided parameters are incorrect.
      content:
        text/html:
          schema:
            $ref: "#/components/schemas/error_message"

    image:
      description: OK
      content:
        html:
          schema:
            type: string
        image/jpeg:
          schema:
            type: string
            format: binary
        image/png:
          schema:
            type: string
            format: binary
        image/svg+xml:
          schema:
            type: string
            format: binary

  schemas:
    error_message:
      title: error message
      description: A text message describing an error.
      type: string
      maxLength: 256

    html:
      description: A html page.
      type: string

    dataset:
      title: dataset
      description: Details about a dataset.
      type: object
      properties:
        url:
          type: string
        dataset_provider:
          type: string
        ecvs:
          description: A list of ECVs
          type: array
          items:
            type: string
        filters:
          description: A list of filters.
          type: array
          items:
            title: filter
            type: object
            properties:
              drs: # key could be lots of things
                type: string
        relationships:
          description: A list of relationships.
          type: array
          items:
            title: dataset_relationship
            type: object
            properties:
              relationship_types:
                description: A list of relationship types.
                type: array
                items:
                  type: string
              related_dataset:
                type: string
              related_dataset_start_date:
                type: string
              related_dataset_end_date:
                type: string
              description:
                type: string

paths:
  # A list of dataset/filter combinations for a dataset URL
  /dataset/{url}:
    parameters:
      - $ref: "#/components/parameters/url"
      - $ref: "#/components/parameters/format_param"

    get:
      tags:
        - dataset
      summary: Get relationship information for a dataset with the given URL.
      description: Retrieves data about the dataset/filter combinations and their relationships to other datasets for a given dataset URL.
      operationId: getDatasetsByURL
      responses:
        "200":
          $ref: "#/components/responses/dataset_list"
        "404":
          $ref: "#/components/responses/error_message"

  # List all dataset
  /dataset/:
    parameters:
      - $ref: "#/components/parameters/format_param"

    get:
      tags:
        - dataset
      summary: Get a list of all datasets.
      description: |
        Retrieves data about all datasets and their relationships to other datasets.
        There may be multiple results for a dataset, the combination of dataset and filters is unique.
      operationId: getDatasets
      responses:
        "200":
          $ref: "#/components/responses/dataset_list"

  # A sankey diagram for dataset URL
  /sankey/{url}:
    parameters:
      - $ref: "#/components/parameters/url"
      - $ref: "#/components/parameters/sankey_format_param"

    get:
      tags:
        - sankey
      summary: Get a sankey diagram for a dataset URL.
      description: Generate a sankey diagram for a dataset URL, showing filters and relationships.
      operationId: getSankeyByURL
      responses:
        "200":
          $ref: "#/components/responses/image"
        "404":
          $ref: "#/components/responses/error_message"


  # A sankey diagram for a project
  /sankey/{project}:
    parameters:
      - $ref: "#/components/parameters/project"
      - $ref: "#/components/parameters/sankey_format_param"

    get:
      tags:
        - sankey
      summary: Get a sankey diagram for a project.
      description: Generate a sankey diagram for a project, showing filters and relationships.
      operationId: getSankeyByProject
      responses:
        "200":
          $ref: "#/components/responses/image"
        "404":
          $ref: "#/components/responses/error_message"


  # List all projects
  /project/:
    parameters:
      - $ref: "#/components/parameters/format_param"

    get:
      tags:
        - project
      summary: Get a list of all projects.
      description: Retrieves a list of projects.
      operationId: getProjects
      responses:
        "200":
          $ref: "#/components/responses/project_list"


  # List all relation types
  /relationtype/:
    parameters:
      - $ref: "#/components/parameters/format_param"

    get:
      tags:
        - relationtype
      summary: Get a list of all relation types.
      description: Retrieves a list of relation types.
      operationId: getRelationTypes
      responses:
        "200":
          $ref: "#/components/responses/relationtype_list"
