raido-openapi-3.0.yaml

openapi: 3.0.3

servers:
  - url: 'https://api.prod.raid.org.au'
    description: The production service - "PROD".
  - url: 'https://api.demo.raid.org.au'
    description: >
      DEMO environment, used for client integration testing and 
      customer demonstrations.
  - url: 'https://api.test.raid.org.au'
    description: >
      dev environment, used for developer integration testing.
  - url: 'http://localhost:8080'
    description: Local development.
    
info:
  title: RAID v2 API
  version: 2.0.0
  description: >
    This file is where all the endpoint paths are defined, it's the "top level'
    of the OpenAPI definition that links all the different files together.
    The `3.0` in the filename refers to this file being based on OpenAPI 3.0 
    as opposed to OpenAPI 3.1, which the tooling doesn't support yet.
    The `2.0.0` in the version field refers to the fact that there's already 
    a `1.0.0` used for the legacy RAiD application.
    Note that swagger ui doesn't currently work with our spec, 
    see https://github.com/swagger-api/swagger-ui/issues/7724
    But the spec works fine with openapi-generator tooling.

  contact:
    name: ARDC RAiD team
    email: contact@raid.org
  termsOfService: https://github.com/au-research/raido/blob/main/doc/service-level-guide.md
tags:
  - name: public-experimental
    description: The APIs are not stable, they may change at any time.  
      Can be called without auth.
  - name: public-stable
    description: >
      The APIs are stable and will be supported in to the future,
      as per the service-level-guide.  
      Can be called without auth.
  - name: basic-raid-experimental
    description: The APIs are not stable, they may change at any time.
      These endpoints are intended to be called by the Raido UI.
      Must be called with auth.
  - name: basic-raid-stable
    description: Stable APIs.
security:
  - bearerAuth: []

paths:

  # region raid endpoints
  /raid/:
    $ref: "raid.yaml#/paths/~1raid"
  /raid/{prefix}/{suffix}:
    $ref: "raid.yaml#/paths/~1raid~1{prefix}~1{suffix}"
  /raid/{prefix}/{suffix}/history:
    $ref: "raid.yaml#/paths/~1raid~1{prefix}~1{suffix}~1history"

  # endregion

  # region service point endpoints

  /service-point/:
    $ref: "service-point.yaml#/paths/~1service-point"
  /service-point/{id}:
    $ref: "service-point.yaml#/paths/~1service-point~1{id}"

  # endregion

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        An "api-token" for integration is generated manually via the app-client 
        (on the "API key" page, from the /generate-api-token endpoint). See 
        https://github.com/au-research/raido/blob/main/doc/security/readme.md
        The app-client UI uses an ephemeral api-token returned from the 
        `/idpresponse` URL as part of the OIDC sign-in process.