openapi: 3.1.0

info:
  title: Code Golf API
  description: API for [Code Golf](https://code.golf).
  version: unstable

servers:
  - url: https://code.golf/api

tags:
  - name: achievements
  - name: holes
  - name: languages
  - name: misc
  - name: suggestions
  - name: notes

paths:
  /cheevos:
    get:
      operationId: getAchievements
      tags: [achievements]
      summary: Get all achievements
      responses:
        '200':
          description: A list of achievements
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Achievement'

  /cheevos/{id}:
    get:
      operationId: getAchievementsByID
      parameters:
        - name: id
          description: Achievement ID
          in: path
          required: true
          schema:
            type: string
      tags: [achievements]
      summary: Get an achievement by ID
      responses:
        '200':
          description: A single achievement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Achievement'

  /golfers/{name}:
    get:
      operationId: getGolfersByName
      parameters:
        - name: name
          description: Golfer Name
          in: path
          required: true
          schema:
            type: string
      tags: [golfers]
      summary: Get a golfer by name
      responses:
        '200':
          description: A single golfer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Golfer'

  /holes:
    get:
      operationId: getHoles
      tags: [holes]
      summary: Get all holes
      responses:
        '200':
          description: A list of holes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Hole'

  /holes/{id}:
    get:
      operationId: getHolesByID
      parameters:
        - name: id
          description: Hole ID
          in: path
          required: true
          schema:
            type: string
      tags: [holes]
      summary: Get a hole by ID
      responses:
        '200':
          description: A single hole
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hole'

  /langs:
    get:
      operationId: getLanguages
      tags: [languages]
      summary: Get all languages
      responses:
        '200':
          description: A list of languages
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Language'

  /langs/{id}:
    get:
      operationId: getLanguagesByID
      parameters:
        - name: id
          description: Language ID
          in: path
          required: true
          schema:
            type: string
      tags: [languages]
      summary: Get a language by ID
      responses:
        '200':
          description: A single language
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Language'
  
  /notes:
    get:
      operationId: getUserNotes
      tags: [notes]
      summary: Get all current golfer's notes
      security:
        - cookieAuth: []
      responses:
        '200':
          description: All golfer's notes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Note'
        '403':
          description: Notes access requires authentication
  
  /notes/{hole}/{lang}:
    get:
      operationId: getUserNote
      parameters:
        - name: hole
          description: Hole ID
          in: path
          required: true
          schema:
            type: string
        - name: lang
          description: Language ID
          in: path
          required: true
          schema:
            type: string
      tags: [notes]
      summary: Get current golfer's note for given hole, lang pair
      security:
        - cookieAuth: []
      responses:
        '200':
          description: A golfer's note
          content:
            application/json:
              schema:
                type: string
        '403':
          description: Notes access requires authentication
        '404':
          description: Note does not exist
    put:
      operationId: upsertUserNote
      parameters:
        - name: hole
          description: Hole ID
          in: path
          required: true
          schema:
            type: string
        - name: lang
          description: Language ID
          in: path
          required: true
          schema:
            type: string
      tags: [notes]
      summary: Creates or updates current golfer's note for given hole, lang pair
      security:
        - cookieAuth: []
      responses:
        '204':
          description: Success
        '400':
          description: Invalid hole, lang, or note length
        '402':
          description: Notes are a sponsor-only feature
        '403':
          description: Notes access requires authentication
    delete:
      operationId: deleteUserNote
      parameters:
        - name: hole
          description: Hole ID
          in: path
          required: true
          schema:
            type: string
        - name: lang
          description: Language ID
          in: path
          required: true
          schema:
            type: string
      tags: [notes]
      summary: Deletes current golfer's note for given hole, lang pair, if it exists
      security:
        - cookieAuth: []
      responses:
        '204':
          description: Success
        '400':
          description: Invalid hole or lang
        '403':
          description: Notes access requires authentication

  /suggestions/golfers:
    get:
      operationId: suggestGolfers
      parameters:
        - name: q
          description: Case-insensitive substring to search for
          in: query
          schema:
            type: string
      tags: [suggestions]
      summary: Returns a list of matching golfers, limited to 10
      responses:
        '200':
          description: A JSON array matching golfer names, limited to 10
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /solutions-log:
    get:
      operationId: solutionsLog
      parameters:
        - name: hole
          description: Hole ID
          in: query
          required: true
          schema:
            type: string
        - name: lang
          description: Lang ID
          in: query
          required: true
          schema:
            type: string
      tags: [misc]
      summary: List solutions over time
      responses:
        '200':
          description: A JSON array of solutions over time
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SolutionsLog'

  /solutions-search:
    get:
      operationId: solutionsSearch
      parameters:
        - name: pattern
          description: Regex pattern to search for
          in: query
          required: true
          schema:
            type: string
        - name: hole
          description: Hole ID
          in: query
          required: false
          schema:
            type: string
        - name: lang
          description: Lang ID
          in: query
          required: false
          schema:
            type: string
      tags: [misc]
      security:
        - cookieAuth: []
      summary: Search all current golfer's solutions
      responses:
        '200':
          description: A JSON array of matches
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SolutionsSearchMatch'
        '403':
          description: Solutions search access requires authentication

  /wiki/{slug}:
    get:
      operationId: getWikiPage
      parameters:
        - name: slug
          description: Wiki page ID
          in: path
          required: true
          schema:
            type: string
      tags: [wiki]
      summary: Get a wiki page by its slug
      responses:
        '200':
          description: A single wiki page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WikiPage'

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: __Host-session
  schemas:
    Achievement:
      type: object
      properties:
        description:
          type: string
        emoji:
          type: string
        id:
          type: string
        name:
          type: string

    Golfer:
      type: object
      properties:
        admin:
          type: boolean
        country:
          type:
            - string
            - 'null'
        id:
          type: integer
        name:
          type: string
        pronouns:
          type:
            - string
            - 'null'
        sponsor:
          type: boolean
        started:
          type: string
          format: date-time

    Hole:
      type: object
      properties:
        category:
          type: string
          enum: [Art, Computing, Gaming, Mathematics, Sequence, Transform]
        id:
          type: string
        links:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              url:
                type: string
                format: uri
        name:
          type: string
        preamble:
          type: string

    Language:
      type: object
      properties:
        example:
          type: string
        id:
          type: string
        logo-url:
          type: string
          format: uri
        name:
          type: string
        size:
          type: string
        version:
          type: string
        website:
          type: string
          format: uri  
  
    Note:
      type: object
      properties:
        hole:
          type: string
        lang:
          type: string
        note:
          type: string

    SolutionsLog:
      type: object
      properties:
        bytes:
          type: integer
        chars:
          type: integer
        golfer:
          type: string
        hole:
          type: string
        lang:
          type: string
        scoring:
          type: string
        submitted:
          type: string
          format: date-time

    SolutionsSearchMatch:
      type: object
      properties:
        before:
          type: string
        match:
          type: string
        after:
          type: string
        count:
          type: integer
        hole:
          type: string
        lang:
          type: string
        scoring:
          type: string

    WikiPage:
      type: object
      properties:
        title:
          type: string
        content:
          type: string