<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://wadl.dev.java.net/2009/02"
             xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <doc title="IRISWS metadatachange web service">
    Reports changes detected in station metadata: one record per change, carrying the
    class and detail of what changed, when the change was detected, the station or
    channel epoch it applies to, and a free-text description of the old and new values.
  </doc>

  <grammars>
    <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="unqualified">
      <xsd:element name="Changes">
        <xsd:complexType>
          <xsd:sequence>
            <xsd:element name="Change" minOccurs="0" maxOccurs="unbounded">
              <xsd:complexType>
                <xsd:sequence>
                  <xsd:choice>
                    <xsd:element name="Station">
                      <xsd:complexType>
                        <xsd:attribute name="code" type="xsd:string" use="required"/>
                        <xsd:attribute name="network" type="xsd:string" use="required"/>
                        <xsd:attribute name="starttime" type="xsd:dateTime"/>
                        <xsd:attribute name="endtime" type="xsd:dateTime"/>
                      </xsd:complexType>
                    </xsd:element>
                    <xsd:element name="Channel">
                      <xsd:complexType>
                        <xsd:attribute name="code" type="xsd:string" use="required"/>
                        <xsd:attribute name="location" type="xsd:string" use="required"/>
                        <xsd:attribute name="network" type="xsd:string" use="required"/>
                        <xsd:attribute name="station" type="xsd:string" use="required"/>
                        <xsd:attribute name="starttime" type="xsd:dateTime"/>
                        <xsd:attribute name="endtime" type="xsd:dateTime"/>
                      </xsd:complexType>
                    </xsd:element>
                  </xsd:choice>
                  <xsd:element name="Description" type="xsd:string"/>
                </xsd:sequence>
                <xsd:attribute name="class" type="xsd:string" use="required"/>
                <xsd:attribute name="detail" type="xsd:string" use="required"/>
                <xsd:attribute name="changetime" type="xsd:dateTime" use="required"/>
              </xsd:complexType>
            </xsd:element>
          </xsd:sequence>
        </xsd:complexType>
      </xsd:element>
    </xsd:schema>
  </grammars>

  <resources base="https://service.earthscope.org/irisws/metadatachange/1/">

    <resource path="query">
      <method name="GET" id="query">
        <doc title="Query metadata changes">
          Every parameter is optional; with none, all changes are returned. Different
          parameters are combined with AND. A parameter that takes a list is a
          comma-separated list whose values are combined with OR. Network, station,
          location, channel, class and detail values accept the wildcards * (any
          characters) and ? (one character). Each parameter may appear once; an unknown or
          repeated parameter is rejected with 400. Times are ISO 8601 (for example
          2024-01-31T12:00:00, 2024-01-31T12:00:00Z or the ordinal form 2024-031T12:00:00)
          and are taken as UTC when no offset is given.
        </doc>
        <request>
          <param name="net" style="query" type="xsd:string">
            <doc>Network codes, 1-2 characters each. Alias: network.</doc>
          </param>
          <param name="network" style="query" type="xsd:string">
            <doc>Alias for net.</doc>
          </param>
          <param name="sta" style="query" type="xsd:string">
            <doc>Station codes, 1-5 characters each. Alias: station.</doc>
          </param>
          <param name="station" style="query" type="xsd:string">
            <doc>Alias for sta.</doc>
          </param>
          <param name="loc" style="query" type="xsd:string">
            <doc>Location codes, 1-2 characters each. Use -- for an empty location code. Alias: location.</doc>
          </param>
          <param name="location" style="query" type="xsd:string">
            <doc>Alias for loc.</doc>
          </param>
          <param name="cha" style="query" type="xsd:string">
            <doc>Channel codes, 1-3 characters each. Aliases: chan, channel.</doc>
          </param>
          <param name="chan" style="query" type="xsd:string">
            <doc>Alias for cha.</doc>
          </param>
          <param name="channel" style="query" type="xsd:string">
            <doc>Alias for cha.</doc>
          </param>

          <param name="starttime" style="query" type="xsd:dateTime">
            <doc>Only epochs that start on or after this time.</doc>
          </param>
          <param name="endtime" style="query" type="xsd:dateTime">
            <doc>Only epochs that end on or before this time. Must not be before starttime.</doc>
          </param>
          <param name="startchange" style="query" type="xsd:dateTime">
            <doc>Only changes detected on or after this time.</doc>
          </param>
          <param name="endchange" style="query" type="xsd:dateTime">
            <doc>Only changes detected on or before this time. Must not be before startchange.</doc>
          </param>

          <param name="class" style="query" type="xsd:string">
            <doc>
              Change classes, case-insensitive, for example Channel, ChannelLocation,
              ChannelOrientation, ChannelSensor.
            </doc>
          </param>
          <param name="detail" style="query" type="xsd:string">
            <doc>
              Change details within a class, case-insensitive, for example Latitude,
              Longitude, Azimuth, EndTimeChange, DigitalResponse.
            </doc>
          </param>
          <param name="description" style="query" type="xsd:string">
            <doc>
              A single case-insensitive pattern matched against the whole description text,
              with * and ? as wildcards; use *text* to match text anywhere in it. Not a list.
            </doc>
          </param>

          <param name="limit" style="query" type="xsd:int">
            <doc>Return at most this many changes. Must be 1 or greater.</doc>
          </param>
          <param name="format" style="query" type="xsd:string" default="xml">
            <doc>Response format. Only xml is produced.</doc>
            <option value="xml" mediaType="application/xml"/>
          </param>
        </request>

        <response status="200">
          <doc>
            The matching changes. A query that matches nothing still returns 200, with an
            empty Changes element.
          </doc>
          <representation mediaType="application/xml" element="Changes"/>
        </response>
        <response status="400">
          <doc>
            Invalid request: an unknown or repeated parameter, a malformed network code, a
            limit below 1, an unsupported format, or a time range whose end is before its
            start.
          </doc>
          <representation mediaType="text/plain"/>
        </response>
        <response status="500">
          <doc>Internal error, including an unparseable time value.</doc>
          <representation mediaType="text/plain"/>
        </response>
      </method>
    </resource>

    <resource path="version">
      <method name="GET" id="version">
        <doc title="Service version"/>
        <response status="200">
          <representation mediaType="text/plain"/>
        </response>
      </method>
    </resource>

    <resource path="application.wadl">
      <method name="GET" id="wadl">
        <doc title="This WADL document"/>
        <response status="200">
          <representation mediaType="application/xml"/>
        </response>
      </method>
    </resource>

  </resources>
</application>
