swagger.yaml

openapi: 3.0.0
info:
  version: 0.3.1
  title: sc3MicroAPI
  description: API specification for the WS retrieving information about networks and stations from SeisComP3
  license:
    name: GPLv3
    url: 'https://www.gnu.org/licenses/gpl-3.0.html'
  contact:
    name: Javier Quinteros
    url: >-
      https://www.gfz-potsdam.de/staff/javier.quinteros/sec24
    email: javier@gfz-potsdam.de
servers:
  - url: 'http://localhost:7000/sc3microapi'
    description: sc3MicroAPI running locally
paths:
  /:
    get:
      summary: Get a help page with a minimum documentation of the service.
      description: >-
        Returns a help page in HTML format with a minimum description on how the
        service can be used and how to configure it.
      responses:
        '200':
          description: Minimum service documentation.
          content:
            text/html:
              schema:
                type: string
  /version:
    get:
      summary: Get version of the code
      description: Returns a string specifying the version.
      responses:
        '200':
          description: Version of the code
          content:
            text/plain:
              schema:
                type: string
  /network:
    get:
      summary: Get a list of networks and its properties
      description: >-
        Returns a list of networks including all its attributes and filtered
        based on the parameters sent.
      parameters:
        - name: net
          in: query
          description: Network code
          required: false
          schema:
            type: string
        - name: starttime
          in: query
          description: Start time of the time window
          required: false
          schema:
            type: string
            format: date-time
        - name: endtime
          in: query
          description: End time of the time window
          required: false
          schema:
            type: string
            format: date-time
        - name: outformat
          in: query
          description: Format of the response
          required: false
          schema:
            type: string
            default: json
            enum:
              - json
              - text
              - xml
        - name: restricted
          in: query
          description: Specify whether the network is restricted or not.
          required: false
          schema:
            type: number
            format: int
            minimum: 0
            maximum: 1
        - name: archive
          in: query
          description: Acronym of the institution where data is archived.
          required: false
          schema:
            type: string
        - name: netclass
          in: query
          description: Type of network (temporary or permanent).
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of networks filtered based on parameters.
          $ref: '#/components/responses/Networks'
        '204':
          description: No data available with the specified parameters.
        '400':
          description: >-
            Bad request due to improper specification, unrecognized parameter,
            parameter value out of range, etc.
          $ref: '#/components/responses/ErrorResponse'
        '404':
          description: Unknown error while querying the available networks.
          $ref: '#/components/responses/ErrorResponse'
  /station:
    get:
      summary: Get a list of stations and its properties
      description: >-
        Returns a list of stations including all its attributes and filtered
        based on the parameters sent.
      parameters:
        - name: net
          in: query
          description: Network code
          required: false
          schema:
            type: string
        - name: sta
          in: query
          description: Station code
          required: false
          schema:
            type: string
        - name: starttime
          in: query
          description: Start time of the time window
          required: false
          schema:
            type: string
            format: date-time
        - name: endtime
          in: query
          description: End time of the time window
          required: false
          schema:
            type: string
            format: date-time
        - name: outformat
          in: query
          description: Format of the response
          required: false
          schema:
            type: string
            default: json
            enum:
              - json
              - text
              - xml
        - name: restricted
          in: query
          description: Specify whether the network is restricted or not.
          required: false
          schema:
            type: number
            format: int
            minimum: 0
            maximum: 1
        - name: archive
          in: query
          description: Acronym of the institution where data is archived.
          required: false
          schema:
            type: string
        - name: shared
          in: query
          description: Specify whether the network is shared with EIDA.
          required: false
          schema:
            type: number
            format: int
            minimum: 0
            maximum: 1
      responses:
        '200':
          description: List of stations filtered based on parameters.
          $ref: '#/components/responses/Stations'
        '204':
          description: No data available with the specified parameters.
        '400':
          description: >-
            Bad request due to improper specification, unrecognized parameter,
            parameter value out of range, etc.
          $ref: '#/components/responses/ErrorResponse'
        '404':
          description: Unknown error while querying the available stations.
          $ref: '#/components/responses/ErrorResponse'
  /virtualnet:
    get:
      summary: Get a list of virtual networks and its properties
      description: >-
        Returns a list of virtual networks including all its attributes and filtered
        based on the parameters sent.
      parameters:
        - name: net
          in: query
          description: Network code
          required: false
          schema:
            type: string
        - name: starttime
          in: query
          description: Start time of the time window
          required: false
          schema:
            type: string
            format: date-time
        - name: endtime
          in: query
          description: End time of the time window
          required: false
          schema:
            type: string
            format: date-time
        - name: outformat
          in: query
          description: Format of the response
          required: false
          schema:
            type: string
            default: json
            enum:
              - json
              - text
              - xml
        - name: typevn
          in: query
          description: Type of virtual network.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of virtual networks filtered based on parameters.
          $ref: '#/components/responses/VNetworks'
        '204':
          description: No data available with the specified parameters.
        '400':
          description: >-
            Bad request due to improper specification, unrecognized parameter,
            parameter value out of range, etc.
          $ref: '#/components/responses/ErrorResponse'
        '404':
          description: Unknown error while querying the available virtual networks.
          $ref: '#/components/responses/ErrorResponse'
  /access:
    get:
      summary: Check if a particular user has access to data
      description: Check if a user has access granted to certain networks/station/channel.
      parameters:
        - name: nslc
          in: query
          description: Network.Station.Location.Channel code
          required: true
          schema:
            type: string
        - name: email
          in: query
          description: Email account of the user
          required: true
          schema:
            type: string
            format: email
        - name: starttime
          in: query
          description: Start time of the time window
          required: false
          schema:
            type: string
            format: date-time
        - name: endtime
          in: query
          description: End time of the time window
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Access to data is allowed. Response will be empty.
          content:
            text/plain:
              schema:
                format: string
        '400':
          description: >-
            Bad request due to improper specification, unrecognized parameter,
            parameter value out of range, etc.
          $ref: '#/components/responses/ErrorResponse'
        '403':
          description: Unknown error while querying the available networks.
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    Network:
      description: Seismic network.
      type: object
      properties:
        code:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        netclass:
          type: string
        archive:
          type: string
        restricted:
          type: integer
    Station:
      description: Seismic station.
      type: object
      properties:
        network:
          type: string
        code:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        elevation:
          type: number
        place:
          type: string
        country:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        restricted:
          type: integer
        shared:
          type: integer
    VNetwork:
      description: Seismic network.
      type: object
      properties:
        code:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        type:
          type: string
    StdErrorSchema:
      description: Bad Request.
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  responses:
    Networks:
      description: List of networks filtered based on the parameters.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#components/schemas/Network'
        text/plain:
          schema:
            type: string
          examples:
            plainnetwork:
              value: >-
                code|start|end|netClass|archive|restricted|PI GE|1993-01-01
                00:00:00||p|GFZ|0|geofon@gfz-potsdam.de
    Stations:
      description: List of stations filtered based on the parameters.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#components/schemas/Station'
        text/plain:
          schema:
            type: string
          examples:
            plainstation:
              value: >-
                code|start|end|netClass|archive|restricted|PI GE|1993-01-01
                00:00:00||p|GFZ|0|geofon@gfz-potsdam.de
    VNetworks:
      description: List of virtual networks filtered based on the parameters.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#components/schemas/VNetwork'
        text/plain:
          schema:
            type: string
          examples:
            plainvnetwork:
              value: >-
                code|start|end|netClass|archive|restricted|PI GE|1993-01-01
                00:00:00||p|GFZ|0|geofon@gfz-potsdam.de
    ErrorResponse:
      description: Error Response.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#components/schemas/StdErrorSchema'