objects.xml

<chapter>
  <title>Objects</title>
  <para>
    As the protocol is REST-based the base elements of it are objects.
  </para>
  <para>
    There are several types of objects:
    <glosslist>
      <glossentry>
        <glossterm>product</glossterm>
        <glossdef>
          <para>
            A single program, library or package.
          </para>
        </glossdef>
      </glossentry>
      <glossentry>
        <glossterm>component</glossterm>
        <glossdef>
          <para>
            Part of program, library of package.
          </para>
        </glossdef>
      </glossentry>
      <glossentry>
        <glossterm>bug</glossterm>
        <glossdef>
          <para>
            A single problem.
          </para>
        </glossdef>
      </glossentry>
      <glossentry>
        <glossterm>comment</glossterm>
        <glossdef>
          <para>
           A comment about the bug.
          </para>
        </glossdef>
      </glossentry>
      <glossentry>
        <glossterm>attachment</glossterm>
        <glossdef>
          <para>
           A file attachment to bug.
          </para>
        </glossdef>
      </glossentry>
      <glossentry>
        <glossterm>person</glossterm>
        <glossdef>
          <para>
            A person (reporter, developer or administrator).
          </para>
        </glossdef>
      </glossentry>
    </glosslist>
  </para>
  <sect1>
    <title>Elements common for all types of object</title>
    <para>
      There are several properties and actions shared among the objects
    </para>
    <sect2>
      <title>Properties</title>
        <para>
        Each object has following properties:
        <glosslist>
          <glossentry>
            <glossterm>uuid</glossterm>
            <glossdef>
              <para>
                The uuid number which identifies single object. The uuid MUST be
                unique. It MUST NOT change.
              </para>
            </glossdef>
          </glossentry>
          <glossentry>
            <glossterm>name</glossterm>
            <glossdef>
              <para>
                The human-readable name. The implementation SHOULD handle
                urlencoded form as an equivalent of uuid if it identifies
                the object (i.e. there are no duplicates of names).
              </para>
            </glossdef>
          </glossentry>
          <glossentry>
            <glossterm>link</glossterm>
            <glossdef>
              <para>
                It indicates to which server the object belongs to.
                It can occure in two cases:
                <orderedlist>
                  <listitem>
                    <para>
                      The object is cached in server (for whatever reason) but
                      the most current version is pointed by the uri of this
                      property.
                    </para>
                    <para>
                      In this case the implementation MAY remove the object in
                      this case in future to save the disk space.
                    </para>
                  </listitem>
                </orderedlist>
                or
                <orderedlist continuation="continues" >
                  <listitem>
                    <para>
                      The object has been moved in the specified address from
                      this bug tracker.
                    </para>
                    <para>
                      The implementation MUST NOT remove the object from it's
                      database.
                    </para>
                  </listitem>
                </orderedlist>
              </para>
              <para>
                In both cases the implementation MAY return the 302 (Found)
                return code.
              </para>
              <para>
                The client SHOULD update its inner reference.
              </para>
            </glossdef>
          </glossentry>
          <glossentry>
            <glossterm>stored</glossterm>
            <glossdef>
              <para>
                Used with the link property. If it set to true it indicates that
                the object will be stored pernamently. If to false it may be
                removed in future.
              </para>
            </glossdef>
          </glossentry>
          <glossentry>
            <glossterm>history</glossterm>
            <glossdef>
              <para>
                It is a special object denoting the history. It SHOULD NOT be
                included in default response but after the /history action.
                It indicates the changes of the bug.
              </para>
            </glossdef>
          </glossentry>
        </glosslist>
      </para>
    </sect2>
    <sect2>
      <title>Actions</title>
      <para>
        In this section there are described the actions which are not covered
        by REST or the extensions to those actions.
      </para>
      <sect3>
        <title>List (REST)</title>
        <para>
          This is standard REST action done by GET without UUID. However if 
          <userinput>propertyname=value1,value2</userinput> is added that only
          records with those property should be listed.
        </para>
        <para>
          The sorting is forced by <userinput>sort=property,dir</userinput>,
           where dir can be eighter DESC (descending) or ASC (ascending).
        </para>
      </sect3>
      <sect3>
        <title>Show (REST)</title>
        <para>
          This is standard REST action done by GET with the object.
        </para>
      </sect3>
      <sect3>
        <title>Create (REST)</title>
        <para>
          This is standard REST action done by POST. As a result the redirection
          to the new object is performed.
        </para>
      </sect3>
      <sect3>
        <title>Update (REST)</title>
        <para>
          The object is updated according to the data send.
        </para>
      </sect3>
      <sect3>
        <title>Move</title>
        <para>
          The basic concept of the NetBug is that the different bug-related
          resources are on different servers. For varied reasons the object
          is required to be moved.
        </para>
        <para>
          The procedure consist of several steps performed on the both servers.
          Please note that implementation SHOULD provide some security systems
          - such as moderation and/or allowing only for the developers - not
          covered by this document.
        </para>
        <orderedlist>
          <listitem>
            <para>
              A move action is sended to server with the parameter
              <parameter class="function">to</parameter>. I.e.
              <userinput>
                POST /object/uuid/move?to=https%3A%2F%2Fexample.com%2F
              </userinput>
            </para>
            <para>
              <userinput>/object/uuid/</userinput> is the current location of
              object while <userinput>http%3A%2F%2Fexample.com%2F</userinput>
              is urlencoded prefix of future location.
            </para>
          </listitem>
          <listitem>
            <para>
              The 307 HTTP code is returned (Temporary Redirect) and client
              is redirected to
              <returnvalue>
                to/object/receive?from=from/object/uuid&amp;code=code
              </returnvalue>
            </para>
            <para>
              The <parameter class="function">to</parameter> is the new location
              of object while <returnvalue>from/object/uuid</returnvalue> is
              current location. <returnvalue>code</returnvalue> is a temporary
              passphrase. It MUST be valid for at least 30 minutes.
            </para>
            <para>
              Please note that the server MAY response by 403 or 401 error code
              (Forbidden, Unauthorized) if the client has not logged into the
              account with the permission to move the object.
            </para>
          </listitem>
          <listitem>
            <para>
              The redirection by client is performed. The server sends the code
              to orginal server:
              <userinput>GET /object/uuid/export?code=code</userinput>.
              On this request the original server MUST export the requested
              object and all child objects (including its history) to XML.
              Then it send it back.
            </para>
            <para>
              The original server should set the location properly after the
              process. If any attamp was made to modify any of those object
              the 400 error code should be returned.
            </para>
          </listitem>
        </orderedlist>
        <para>
          The implementation SHOULD try to connect by TLS/SSL if possible
          falling back to plain http on fail.
        </para>
      </sect3>
    </sect2>
  </sect1>
</chapter>