swagger.yml

openapi: "3.0.0"
info:
  title: Miiify API
  version: "v1.0.0"
  description: "Miiify is web annotation server"
servers:
  - url: https://miiify.rocks
paths:
  /:
    get:
      tags:
        - welcome message
      summary: Hello Miiify!
      description: Displays a welcome message from root path.
      responses:
        "200":
          description: OK
          content:
            text/html:
              schema:
                type: string
              examples:
                html:
                  summary: A welcome message
                  value: OK

  /version:
    get:
      tags:
        - version message
      summary: Miiify version!
      description: Displays the current version.
      responses:
        "200":
          description: OK
          content:
            text/html:
              schema:
                type: string
              examples:
                html:
                  summary: Version message
                  value: 1.0.0

  /annotations/:
    post:
      tags:
        - create container
      summary: create a new container
      description: Creates a new container to store annotations. Please refer to the Web Annotation Data Model for a description on the JSON that can be used.
      parameters:
        - in: header
          name: Host
          schema:
            type: string
            example: miiify.rocks
            description: Override the default host sent from client.
          required: false
        - in: header
          name: Slug
          schema:
            type: string
            example: my-container
            description: Specify the container name. If not supplied a system generated name with be used.
          required: false
      requestBody:
        required: true
        description: Basic container data
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/container"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/container"
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error

  /annotations/{container_id}/:
    post:
      tags:
        - create annotation
      summary: add annotation to collection
      description: Creates a new annotation and adds it to the container collection. Please refer to the Web Annotation Data Model for a description on the JSON that can be used. Currently Miiify will only check the type field is valid and there is no id key supplied.
      parameters:
        - in: header
          name: Host
          schema:
            type: string
            example: miiify.rocks
            description: Override the default host sent from client.
          required: false
        - in: header
          name: Slug
          schema:
            type: string
            example: annotation1
            description: Specify the annotation name. If not supplied a system generated name with be used.
          required: false
        - name: container_id
          in: path
          required: true
          description: the unique identifier of a container
          schema:
            type: string
      requestBody:
        required: true
        description: Basic annotation data
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/annotation"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/annotation"
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error

    get:
      tags:
        - retrieve annotation collection or annotation page
      summary: retrieve annotation collection
      description: Retrieve the annotations as a collection or annotation page.
      parameters:
        - in: query
          name: page
          schema:
            type: integer
          description: Access individual pages.
        - in: header
          name: If-None-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for supporting caching."
          required: false
        - in: header
          name: Prefer
          schema:
            type: string
            default: return=representation;include="https://www.w3.org/ns/oa#PreferContainedDescriptions"
            enum:
              - return=representation;include="https://www.w3.org/ns/oa#PreferContainedDescriptions"
              - return=representation;include="https://www.w3.org/ns/oa#PreferContainedIRIs"
              - return=representation;include="https://www.w3.org/ns/ldp#PreferMinimalContainer"
            description: "ETag support for comparing uniqueness."
          required: false
        - name: container_id
          in: path
          required: true
          description: the unique identifier of a container
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/collection"
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "304":
          description: Not Modified
        "500":
          description: Internal Server Error

  /annotations/{container_id}:
    get:
      tags:
        - retrieve container
      summary: retrieve container details
      description: Retrieve the details of a container.
      parameters:
        - in: header
          name: If-None-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for supporting caching."
          required: false
        - name: container_id
          in: path
          required: true
          description: the unique identifier of a container
          schema:
            type: string
      responses:
        "200":
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/container"
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "304":
          description: Not Modified
        "500":
          description: Internal Server Error

    put:
      tags:
        - modify container
      summary: modify a container
      description: Modify a single container. The id field within the JSON payload must match the id field in the container being modified."
      parameters:
        - in: header
          name: Host
          schema:
            type: string
            example: miiify.rocks
            description: Override the default host sent from client.
          required: false
        - in: header
          name: If-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for comparing uniqueness.."
          required: false
        - name: container_id
          in: path
          required: true
          description: the unique identifier of a container
          schema:
            type: string
      responses:
        "200":
          description: success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/container"
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "412":
          description: Precondition Failed
        "500":
          description: Internal Server Error

    delete:
      tags:
        - delete container
      summary: delete container and its collection
      description: Deletes a container including its entire collection.
      parameters:
        - in: header
          name: If-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for comparing uniqueness."
          required: false
        - name: container_id
          in: path
          required: true
          description: the unique identifier of a container
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "412":
          description: Precondition Failed
        "500":
          description: Internal Server Error

  /annotations/{container_id}/{annotation_id}:
    get:
      tags:
        - retrieve annotation
      summary: "retrieve annotation"
      description: "Retrieve a single annotation from a container."
      parameters:
        - in: header
          name: If-None-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for supporting caching."
          required: false
        - in: header
          name: Prefer
          schema:
            type: string
            default: return=representation;include="https://www.w3.org/ns/oa#PreferContainedDescriptions"
            enum:
              - return=representation;include="https://www.w3.org/ns/oa#PreferContainedDescriptions"
              - return=representation;include="https://www.w3.org/ns/oa#PreferContainedIRIs"
              - return=representation;include="https://www.w3.org/ns/ldp#PreferMinimalContainer"
            description: "ETag support for comparing uniqueness."
          required: false
        - name: container_id
          in: path
          required: true
          description: the unique identifier of a container
          schema:
            type: string
        - name: annotation_id
          in: path
          required: true
          description: the unique identifier of an annotation
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/annotation"
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "304":
          description: Not Modified
        "500":
          description: Internal Server Error

    put:
      tags:
        - modify annotation
      summary: "modify annotation"
      description: "Modify a single annotation within a container. The id field within the JSON payload must match the id field in the annotation being modified."
      parameters:
        - in: header
          name: Host
          schema:
            type: string
            example: miiify.rocks
            description: Override the default host sent from client.
          required: false
        - in: header
          name: If-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for comparing uniqueness.."
          required: false
        - name: container_id
          in: path
          required: true
          description: the unique identifier of a container
          schema:
            type: string
        - name: annotation_id
          in: path
          required: true
          description: the unique identifier of an annotation
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/annotation"
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "412":
          description: Precondition Failed
        "500":
          description: Internal Server Error

    delete:
      tags:
        - delete annotation
      summary: "delete annotation"
      description: "Delete a single annotation from a container."
      parameters:
        - in: header
          name: If-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for comparing uniqueness.."
          required: false
        - name: container_id
          in: path
          required: true
          description: the unique identifier of a container
          schema:
            type: string
        - name: annotation_id
          in: path
          required: true
          description: the unique identifier of an annotation
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "412":
          description: Precondition Failed
        "500":
          description: Internal Server Error

  /manifest/{key}:
    post:
      tags:
        - create manifest
      summary: "add manifest"
      description: Creates a new manifest.
      parameters:
        - name: key
          in: path
          required: true
          description: replace value with key
          schema:
            type: string
      requestBody:
        required: true
        description: Manifest data
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/manifest"
      responses:
        "201":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/manifest"
        "400":
          description: Bad Request
        "500":
          description: Internal Server Error

    put:
      tags:
        - modify manifest
      summary: "update manifest"
      description: "Updates an existing manifest."
      parameters:
        - in: header
          name: If-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for comparing uniqueness.."
          required: false
        - name: key
          in: path
          required: true
          description: update value with key
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/manifest"
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "412":
          description: Precondition Failed
        "500":
          description: Internal Server Error

    get:
      tags:
        - retrieve manifest
      summary: "retrieve manifest"
      description: "Retrieve a manifest."
      parameters:
        - in: header
          name: If-None-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for supporting caching."
          required: false
        - name: key
          in: path
          required: true
          description: the key to retrieve value
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/manifest"
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "304":
          description: Not Modified
        "500":
          description: Internal Server Error

    delete:
      tags:
        - delete manifest
      summary: "delete manifest"
      description: "Delete a manifest."
      parameters:
        - in: header
          name: If-Match
          schema:
            type: string
            example: "caa80ca1e4cc5f2253df5ee35293236350b19194"
            description: "ETag support for comparing uniqueness.."
          required: false
        - name: key
          in: path
          required: true
          description: the key to delete value
          schema:
            type: string
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
        "404":
          description: Not Found
        "412":
          description: Precondition Failed
        "500":
          description: Internal Server Error

components:
  schemas:
    container:
      type: object
      properties:
        type:
          example:
            - BasicContainer
            - AnnotationCollection
          description: An example type for differentiating a container from an annotation.

    annotation:
      type: object
      properties:
        type:
          type: string
          example: Annotation
          description: An example type for differentiating an annotation from a container.

    collection:
      type: object
      properties:
        type:
          example:
            - BasicContainer
            - AnnotationCollection
          description: An example type for differentiating a collection from an annotation.

    page:
      type: object
      properties:
        type:
          example: AnnotationPage
          description: An example type for differentiating a page from an annotation.

    manifest:
      type: object
      properties:
        type:
          type: string
          example: Manifest
          description: An example type for differentiating a manifest from an annotation or container.