openapi.yaml

openapi: "3.1.0"
info:
  version: "0.1.0"
  title: "Ace Archive API"
  description: |
    An API for querying metadata about artifacts in [Ace
    Archive](https://acearchive.lgbt).

    This API is currently experimental. The API is `v0`, which means that
    **backwards-incompatible** changes could happen **at any time**.

    You do not need an API key to use this API.
  contact:
    url: "https://github.com/acearchive/acearchive.lgbt/issues"
    email: "contact@acearchive.lgbt"
  license:
    name: "MIT"
    identifier: "MIT"
servers:
  - url: "https://api.acearchive.lgbt/v0"
paths:
  /artifacts/{id}:
    get:
      summary: "Get an artifact"
      description: |
        Get a single artifact in the archive by its ID.
      parameters:
        - name: id
          in: path
          required: true
          description: |
            The unique ID of the artifact.
          example: "PZsGT3uJ1FXk"
          schema:
            type: string
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Artifact"
        "404":
          description: "Artifact Not Found"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "4XX":
          $ref: "#/components/responses/UnexpectedError"
        "5XX":
          $ref: "#/components/responses/UnexpectedError"
  /artifacts/:
    get:
      summary: "List artifacts"
      description: |
        Page through artifacts in the archive.

        The order of the returned artifacts when paging is consistent, but how
        they are sorted (by date, by title, etc.) is unspecified.
      parameters:
        - name: "cursor"
          in: "query"
          description: |
            An opaque string cursor for pagination.

            Each page (except the final page) includes a cursor which can be
            passed as a query argument to get the next page.
          example: "HDv61FcS0TO7v4UYKaFIWLpI5xiD8b7sn5_U5Xrjzm2cb0yoxLhcwXyBV0Ht8XsRBUxpmB8cUwlCI4OU"
          schema:
            type: string
        - name: "limit"
          in: "query"
          description: |
            The maximum number of artifacts to return in a page.

            The size of a page may be smaller than this value, even if it's not
            the final page.
          example: 50
          schema:
            type: integer
            format: int32
            default: 10
            minimum: 1
            maximum: 250
      responses:
        "200":
          description: "OK"
          content:
            application/json:
              schema:
                type: object
                required:
                  - items
                properties:
                  items:
                    type: array
                    description: |
                      The artifacts in the current page.

                      If this array is empty or smaller than the given `limit`,
                      it does not necessarily mean there are no more pages. The
                      only way to determine if there are more pages is to check
                      if there is a `next_cursor`.
                    items:
                      $ref: "#/components/schemas/Artifact"
                  next_cursor:
                    type: string
                    description: |
                      An opaque string cursor for pagination.

                      This cursor can be passed as a query argument to get the
                      next page. If there is no `next_cursor`, then the current
                      page is the final page.

                      If there is a `next_cursor`, then there are more pages,
                      even if `items` is empty or smaller than the given
                      `limit`.
                    example: "Y89zOPPH-vJ36hizeSPlGJY-svrS_PuAIScz77HsZuuWQ8nYhgJzgsOZ0K-WmxoXAiChVZVirpCNZw=="
        "400":
          description: "Malformed Request"
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "429":
          $ref: "#/components/responses/TooManyRequests"
        "4XX":
          $ref: "#/components/responses/UnexpectedError"
        "5XX":
          $ref: "#/components/responses/UnexpectedError"
components:
  responses:
    TooManyRequests:
      description: "Too Many Requests"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    UnexpectedError:
      description: "Unexpected Error"
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
  schemas:
    Artifact:
      type: object
      title: "Artifact"
      description: |
        An artifact in the archive.
      required:
        - id
        - title
        - summary
        - url
        - url_aliases
        - files
        - links
        - people
        - identities
        - from_year
        - decades
      properties:
        id:
          type: string
          description: |
            The artifact ID.

            Artifact IDs are stable; they don't change once assigned. An
            artifact may be removed from the archive, but its ID will never be
            recycled.
          example: "MKbNWmmhCog6"
        title:
          type: string
          description: |
            The title of the artifact.

            This may use CommonMark-style asterisk syntax to denote
            `<cite></cite>` markup.
          example: "*The Asexual Manifesto*"
        summary:
          type: string
          description: |
            A short summary of the artifact.

            This may use CommonMark-style asterisk syntax to denote
            `<cite></cite>` markup.
          example: >-
            A paper by the Asexual Caucus of the New York Radical Feminists.
        description:
          type: string
          description: |
            A longer description of the artifact.

            This may use CommonMark-style asterisk syntax to denote
            `<cite></cite>` markup.
          example: >-
            A paper by the Asexual Caucus of the New York Radical Feminists in
            which Lisa Orlando outlines a definition asexuality.
        url:
          type: string
          format: uri
          description: |
            The canonical URL of the artifact page on the Ace Archive site.
          example: "https://acearchive.lgbt/artifacts/orlando-the-asexual-manifesto"
        url_aliases:
          type: array
          items:
            type: string
            format: uri
          description: |
            Aliases for the URL of the artifact page on the Ace Archive site.
          example: []
        files:
          type: array
          description: |
            The files associated with this artifact.
          uniqueItems: true
          items:
            type: object
            required:
              - name
              - filename
              - hash
              - hash_algorithm
              - url
              - hidden
            properties:
              name:
                type: string
                description: |
                  The human-readable name of the file.
                example: "Digital Scan"
              filename:
                type: string
                description: |
                  The filename of the file, with an appropriate file extension.

                  No two files in the same artifact will ever have the same
                  filename. However, a filename can change at any time.
                example: "the-asexual-manifesto.pdf"
              media_type:
                type: string
                description: |
                  The IANA media type of the file.

                  This may be excluded if the media type is unknown or there is
                  no suitable media type. In some of these cases, the file
                  contents may be better inferred from the file extension in
                  `filename`.

                  The media type is not required to agree with the file
                  extension of `filename`. It also may be the case that the
                  media type and file extension agree, but one is more or less
                  specific than the other, such as with `.bib` and `text/plain`.

                  The *type* component (`application`, `text`, `image`, etc.)
                  will always be a registered IANA type, but the *subtype*
                  component (`pdf`, `png`, `html`, etc.) may be either a
                  registered subtype or an unofficial subtype in common use. The
                  `media_type` may or may not include *suffix* and *parameter*
                  components.
                example: "application/pdf"
              hash:
                type: string
                pattern: "^[0-9a-f]+$"
                description: |
                  The cryptographic hash of the file encoded as a hexadecimal
                  string.

                  The `hash_algorithm` property contains the hash algorithm used
                  to generate this hash.
                example: "f907ed09addad95bd17de1efe76c7a624ba8144f0e2165edaf832447cded5f54"
              hash_algorithm:
                type: string
                description: |
                  The cryptographic hash algorithm used to generated the `hash`
                  of the file.

                  New hash algorithms may be added to this enum in the future,
                  and it will be considered a semver minor version bump.

                  The names of the hash algorithms in this enum come from the
                  [multiformats codec
                  table](https://github.com/multiformats/multicodec/blob/master/table.csv).
                  Only algorithms with a `permanent` status will be used.
                example: "sha2-256"
                enum:
                  - "sha2-256"
              url:
                type: string
                format: uri
                description: |
                  The URL where this file can be downloaded.
                example: "https://files.acearchive.lgbt/artifacts/orlando-the-asexual-manifesto/the-asexual-manifesto.pdf"
              lang:
                type: string
                description: |
                  The natural language of this file, as an [RFC
                  5646](https://datatracker.ietf.org/doc/html/rfc5646) language
                  tag.

                  This may be excluded if the language is unknown or if a
                  natural language is not applicable (e.g. a photo).
                example: "en"
              hidden:
                type: boolean
                description: |
                  Whether this file is hidden on the Ace Archive site.
                example: false
        links:
          type: array
          description: |
            The links associated with this artifact.
          items:
            type: object
            required:
              - name
              - url
            properties:
              name:
                type: string
                description: |
                  The human-readable name of this link.
                example: "Internet Archive"
              url:
                type: string
                description: |
                  The URL the link points to.
                example: "https://archive.org/details/asexualmanifestolisaorlando"
                format: uri
        people:
          type: array
          description: |
            The people associated with this artifact.
          example:
            - "Lisa Orlando"
            - "Barbara Getz"
          items:
            type: string
        identities:
          type: array
          description: |
            The personal identity labels associated with this artifact.
          example:
            - "asexual"
            - "lesbian"
          items:
            type: string
        from_year:
          type: integer
          description: |
            The year the creative work associated with this artifact was
            published or first released.

            If `to_year` is also specified, this represents the start of a range
            of years.
          example: 1972
        to_year:
          type: integer
          description: |
            The final year that a creative work associated with this artifact
            was published or first released, representing the end of a range of
            years.
          example: 1980
        decades:
          type: array
          description: |
            The list of decades in which a creative work associated with this
            artifact was published or first released.

            This array will always be sorted in ascending order.
          example:
            - 1970
            - 1980
          items:
            type: integer
            multipleOf: 10
    Problem:
      type: object
      required:
        - type
        - title
        - status
        - detail
      title: "Problem"
      description: |
        An [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807)
        `application/problem+json` object.

        This schema disagrees with RFC 7807 in that URI references in the `type`
        and `instance` properties are always [relative URI
        references](https://www.rfc-editor.org/rfc/rfc3986#section-4.1) which
        are not meant to be resolved.

        The rationale behind this decision comes from the [Zalando RESTful API
        Guidelines](https://opensource.zalando.com/restful-api-guidelines/#176).
      properties:
        type:
          type: string
          format: uri-reference
          description: |
            A relative URI reference that identifies the problem type within the
            scope of this API.

            This URI reference should not be expected to be dereferenceable or
            globally unique.
          default: "about:blank"
          example: "/problems/artifact-not-found"
        title:
          type: string
          description: |
            A short, human-readable summary of the problem type.

            This summary is written in English, is typically not localized, and
            intended to be read by engineers.
          example: "Artifact Not Found"
        status:
          type: integer
          description: |
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          format: int32
          minimum: 100
          maximum: 599
          example: 404
        detail:
          type: string
          description: |
            A human-readable explanation specific to this occurrence of the
            problem.

            This explanation is written in English, is typically not localized,
            and intended to be read by engineers.
          example: "Artifact with ID 'Gb0Zb5T28fXT' not found."
        instance:
          type: string
          format: uri-reference
          description: |
            A relative URI reference that identifies the specific occurrence of
            the problem.

            This URI reference should not be expected to be dereferenceable or
            globally unique.
          example: "/artifacts/Gb0Zb5T28fXT"