apidoc.yml

openapi: 3.0.3
info:
  title: Water API - OpenAPI 3.0
  description: |-
    New Access to Water API, Under Development, Stability Not Yet Guaranteed.

    Some useful links:
    - [Water API Repository](https://github.com/USACE/water-api)
    - [The source API definition](https://github.com/USACE/water-api/blob/master/src/main/apidoc.yaml)
  # termsOfService: None yet
  # contact:
    # email: water@usace.army.mil
  # license:
    # name: MIT
    # url: 
  version: 0.2.0
externalDocs:
  description: Developer-Focused Documentation
  url: https://water-docs.corps.cloud
servers:
  - url: https://water-api.corps.cloud
    description: Stable API
  - url: https://develop-water-api.corps.cloud
    description: Development API
  - url: http://localhost
    description: Local Testing
tags:
  - name: provider
    description: Data Provider
  - name: datasource
    description: Datasource is a unique combination of a Provider and Datatype
  - name: location
    description: A geospatial location
  - name: timeseries
    description: A collection of zero or more (timestamp,value) pairs that share common metadata
  - name: timeseries_group
    description: A named collection of zero or more timeseries
  - name: chart
    description: A configured chart, optionally linked to a location
paths:
  /providers:
    get:
      tags:
        - provider
      summary: List Providers
      description: Lists Data Providers
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TODO'          

  /datasources:
    get:
      tags:
        - datasource
      summary: List Datasources
      description: Lists Datasources
  
  /locations:
    get:
      tags:
        - location
      summary: List Locations
      description: Lists Locations
  /locations/{location}:
    get:
      tags:
        - location
      summary: Get Location
      description: Gets One Location
  /providers/{provider}/locations:
    post:
      tags:
        - location
      summary: Create Location(s)
      description: Creates one or more locations
      # operationId: 
      parameters:
        - name: provider
          in: path
          description: Unique Provider Slug
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TODO'          
            application/xml:
              schema:
                $ref: '#/components/schemas/TODO'
        '400':
          description: Invalid ID supplied
        '404':
          description: Pet not found
    put:
      tags:
        - location
      summary: Update Location(s)
      description: Updates one or more locations
      operationId: updatePetWithForm
      parameters:
        - name: provider
          in: path
          description: Unique Provider Slug
          required: true
          schema:
            type: string
      responses:
        '405':
          description: Invalid input

    delete:
      tags:
        - location
      summary: Delete Loaction(s)
      description: Deletes one or more locations

  /providers/{provider}/locations/{location}:
    delete:
      tags:
        - location
      summary: Delete Location
      description: Deletes a single location using the location's unique slug

  /timeseries:
    get:
      tags:
        - timeseries
      summary: List Timeseries
      description: Lists Timeseries
  /providers/{provider}/timeseries:
    post:
      tags:
        - timeseries
      summary: Create Timeseries
      description: Creates One or More Timeseries
    put:
      tags:
        - timeseries
      summary: Update Timeseries
      description: Updates One or More Timeseries
    delete:
      tags:
        - timeseries
      summary: Delete Timeseries
      description: Deletes One or More Timeseries and Associated Values
  /providers/{provider}/timeseries/values:
    post:
      tags:
        - timeseries
      summary: Create/Update Timeseries Values
      description: Creates/Updates Values for One or More Exiting Timeseries
  
  /providers/{provider}/timeseries_groups:
    get:
      tags:
        - timeseries_group
      summary: List Timeseries Groups
      description: Lists Timeseries Groups
    post:
      tags:
        - timeseries_group
      summary: Create Timeseries Groups
      description: Creates One or More New Timeseries Groups
    put:
      tags:
        - timeseries_group
      summary: Update Timeseries Groups
      description: Updates Metadata for One or More Timeseries Groups
    delete:
      tags:
        - timeseries_group
      summary: Delete Timeseries Groups
      description: Deletes One or More Timeseries Groups (and Associated Group Memberships)
  /providers/{provider}/timeseries_groups/{timeseries_group}:
    get:
      tags:
        - timeseries_group
      summary: Get Timeseries Group Detail
      description: Gets Timeseries Group Details for a Single Timeseries Group
  /providers/{provider}/timeseries_groups/{timeseries_group}/members:
    post:
      tags:
        - timeseries_group
      summary: Add Timeseries Group Members
      description: Adds One or More Timeseries to a Timeseries Group
    delete:
      tags:
        - timeseries_group
      summary: Remove Timeseries Group Members
      description: Removes One or More Timeseries from a Timeseries Group
  /providers/{provider}/timeseries_groups/{timeseries_group}/values:
    get:
      tags:
        - timeseries_group
      summary: Stream Timeseries Group Values
      description: Streams Timeseries Values for all timeseries in a timeseries group 
  
  /chart_types:
    get:
      tags:
        - chart
      summary: List Chart Types
      description: Lists supported chart types
  /charts:
    get:
      tags:
        - chart
      summary: List Charts
      description: Lists charts
  /charts/{chart}:
    get:
      tags:
        - chart
      summary: Get Chart Detail / Render
      description: Gets chart detail or renders chart
  /providers/{provider}/charts:
    get:
      tags:
        - chart
      summary: List Charts
      description: Lists charts
    post:
      tags:
        - chart
      summary: Create Chart(s)
      description: Creates one or more charts
  /providers/{provider}/charts/{chart}:
    delete:
      tags:
        - chart
      summary: Delete Chart
      description: Deletes a chart
  /providers/{provider}/charts/{chart}/mapping:
    post:
      tags:
        - chart
      summary: Create Timeseries-Variable Mapping
      description: Creates one or more timeseries-variable mappings for a chart
    delete:
      tags:
        - chart
      summary: Delete Timeseries-Variable mapping
      description: Deletes one or more timeseries-variable mappings from a chart

components:
  schemas:
    TODO:
      type: object
      properties:
        TODO:
          type: integer
          format: int64
          example: 1
    Datasource:
      type: object
      properties:
        provider:
          type: string
          example: lrb
        provider_name:
          type: string
          example: Buffalo District
        datatype:
          type: string
          example: cwms-location
        datatype_name:
          type: string
          example: CWMS Location
        datatype_uri:
          type: string
          example: https://cwms-data.usace.army.mil/cwms-data/location
  # requestBodies:
    # Pet:
    #   description: Pet object that needs to be added to the store
    #   content:
    #     application/json:
    #       schema:
    #         $ref: '#/components/schemas/Pet'
    #     application/xml:
    #       schema:
    #         $ref: '#/components/schemas/Pet'