swagger.yaml

openapi: 3.0.0

info:
  version: 1.2.2
  title: Routing Service API
  description: API specification of the Routing Service
  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: 'https://geofon.gfz-potsdam.de/eidaws/routing/1'
    description: Routing Service at GEOFON

paths:
  /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

  /endpoints:
    get:
      summary: Get a list of URLs pointing to the endpoints providing routes to this Routing Service
      description: Returns a string with a URL in each line. Each URL points to an endpoint providing routes which have been imported into this Routing Service.
      responses:
        '200':
          description: URLs to endpoints
          content:
            text/plain:
              schema:
                type: string

  /localconfig:
    get:
      summary: Get the local routes and virtual networks
      description: Returns an XML file with local routes and virtual networks.
      responses:
        '200':
          description: Routes and virtual networks
          content:
            application/xml:
              schema:
                type: string

  /globalconfig:
    get:
      summary: Get information about the data centre
      description: Returns information as requested by FDSN in JSON format.
      responses:
        '200':
          description: Data centre information
          content:
            application/json:
              schema:
                type: string
      parameters:
        - name: format
          in: query
          description: Format of the output
          required: true
          schema:
            type: string
            enum:
              - "fdsn"


  /info:
    get:
      summary: Get human readable description of the routes included in this instance of the Routing Service.
      description: Returns a description of the routes included in this Routing Service.
      responses:
        '200':
          description: Information about the routes available in this Routing Service.
          content:
            text/plain:
              schema:
                type: string

  /application.wadl:
    get:
      summary: Get the description of the service in WADL format
      description: Returns the WADL description of the Routing Service.
      responses:
        '200':
          description: WADL description of the service
          content:
            application/xml:
              schema:
                type: string

  /query:
    get:
      summary: Get routes to request the (meta)data specified by the parameters
      description: Returns a list of routes which should be used to get the data.
      parameters:
        - name: network
          in: query
          description: Network code
          required: false
          schema:
            type: array
            items:
              type: string
            default: '*'
          style: form
          explode: false
        - name: station
          in: query
          description: Station code
          required: false
          schema:
            type: array
            items:
              type: string
            default: '*'
          style: form
          explode: false
        - name: location
          in: query
          description: Location code
          required: false
          schema:
            type: array
            items:
              type: string
            default: '*'
          style: form
          explode: false
        - name: channel
          in: query
          description: Channel code
          required: false
          schema:
            type: array
            items:
              type: string
            default: '*'
          style: form
          explode: false
        - 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: service
          in: query
          description: Service type
          required: false
          schema:
            type: string
            default: "dataselect"
        - name: minlatitude
          in: query
          description: Limit to stations with latitude larger than or equal to the specified minimum.
          required: false
          schema:
            type: number
            format: float
            minimum: -90.0
            maximum: 90.0
            default: -90.0
        - name: maxlatitude
          in: query
          description: Limit to stations with latitude smaller than or equal to the specified maximum.
          required: false
          schema:
            type: number
            format: float
            minimum: -90.0
            maximum: 90.0
            default: 90.0
        - name: minlongitude
          in: query
          description: Limit to stations with longitude larger than or equal to the specified minimum.
          required: false
          schema:
            type: number
            format: float
            minimum: -180.0
            maximum: 180.0
            default: -180.0
        - name: maxlongitude
          in: query
          description: Limit to stations with longitude smaller than or equal to the specified maximum.
          required: false
          schema:
            type: number
            format: float
            minimum: -180.0
            maximum: 180.0
            default: 180.0
        - name: format
          in: query
          description: Format of the output
          required: false
          schema:
            type: string
            default: "xml"
            enum:
            - "xml"
            - "json"
            - "get"
            - "post"
        - name: alternative
          in: query
          description: Include alternative routes in the output
          required: false
          schema:
            type: boolean
            default: false
            enum:
            - false
            - true

      responses:
        '200':
          $ref: '#/components/responses/Routes'

        '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.
          content:
            text/plain:
              schema:
                type: string

        '413':
          description: Request would result in too much data being returned or the request itself is too large. Returned error message should include the service limitations in the detailed description. Service limits should also be documented in the service WADL.

        '414':
          description: Request URI too large.

        default:
          description: Unexpected error
          content:
            text/plain:
              schema:
                $ref: '#/components/responses/Standard4XXErrorResponse'

    post:
      summary: Get routes to request the (meta)data specified in the body
      description: Returns a list of routes which should be used to get the data.
      requestBody:
        content:
            # a plain text with the time windows
          text/plain:
            schema:
              type: string
      responses:
        '200':
          $ref: '#/components/responses/Routes'

        '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.
          content:
            text/plain:
              schema:
                type: string

        '413':
          description: Request would result in too much data being returned or the request itself is too large. Returned error message should include the service limitations in the detailed description. Service limits should also be documented in the service WADL.

        '414':
          description: Request URI too large.

        default:
          description: Unexpected error
          content:
            text/plain:
              schema:
                $ref: '#/components/responses/Standard4XXErrorResponse'

components:
  schemas:
    ParamsSet:
      description: Set of parameters to create a query together with the URL.
      type: object
      properties:
        net:
         type: string
        sta:
          type: string
        loc:
          type: string
        cha:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        priority:
          type: number

    Route:
      type: object
      properties:
        name:
          type: string
        url:
          type: string
        params:
          description: List of parameters to create many queries with the same URL.
          type: array
          items:
            $ref: '#/components/schemas/ParamsSet'

  responses:
    Routes:
      description: List of routes to request the specified (meta)data.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Route'
        application/xml:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Route'
        text/plain:
          schema:
            type: string
          examples:
            getformat:
              # FIXME How to express the list of urls?
              summary: This is an example of the get format
              value: "http://server.domain/path/query?key=value"
            postformat:
              # FIXME How to express the array of blocks of url and parameters?
              summary: This is an example of the post format
              value: "http://server.domain/path/query\nNET STA LOC CHA 2010-01-01T00:00:00Z 2010-01-02T00:00:00Z"

    Standard4XXErrorResponse:
      description: Bad Request.
      content:
        text/plain:
          schema:
            type: string