openapi: 3.0.1

servers:
  - url: http://127.0.0.1:7070/api
    description: Local server
  - url: https://shortlink.best/api
    description: Production server
  - url: https://shortlink.best/mock
    description: Mock server

# Available options: https://github.com/json-schema-faker/json-schema-faker/tree/master/docs#available-options
x-json-schema-faker:
  locale: en
  min-items: 2
  max-items: 5
  resolve-json-path: true
  useExamplesValue: true

info:
  version: 0.1.0
  title: ShortLink API (LINK BFF)
  description: |
    ShortLink API for managing and retrieving short links.
  contact:
    email: support@shortlink.best
    name: ShortLink repository
    url: https://github.com/shortlink-org/shortlink/issues
  license:
    name: MIT
    url: http://www.opensource.org/licenses/MIT

paths:
  /links:
    get:
      summary: List links
      description: Retrieve a list of all short links with pagination.
      operationId: getLinks
      tags:
        - Link
      parameters:
        - $ref: 'base.yaml#/components/parameters/LimitParam'
        - $ref: 'base.yaml#/components/parameters/CursorParam'
        - in: query
          name: filter
          schema:
            $ref: 'link.yaml#/components/schemas/LinkFilter'
      responses:
        '200':
          $ref: 'link.yaml#/components/responses/PaginatedLinksResponse'
        '500':
          $ref: 'base.yaml#/components/responses/InternalServerError'

    post:
      summary: Add link
      description: Add a new short link.
      operationId: addLink
      tags:
        - Link
      requestBody:
        $ref: 'link.yaml#/components/requestBodies/AddLinkRequest'
      responses:
        '201':
          $ref: 'link.yaml#/components/responses/LinkCreated'
        '400':
          $ref: 'base.yaml#/components/responses/BadRequest'

    put:
      summary: Update links
      description: Update existing links based on a filter. Updates a single link if the 'id' field is specified in the filter.
      operationId: updateLinks
      tags:
        - Link
      requestBody:
        $ref: 'link.yaml#/components/requestBodies/UpdateLinkRequest'
      responses:
        '200':
          $ref: 'link.yaml#/components/responses/LinksUpdated'
        '400':
          $ref: 'base.yaml#/components/responses/BadRequest'
        '404':
          $ref: 'base.yaml#/components/responses/NotFound'

  /links/{hash}:
    get:
      summary: Get link
      description: Retrieve a specific link by its hash.
      operationId: getLink
      tags:
        - Link
      parameters:
        - $ref: 'link.yaml#/components/parameters/LinkHashParam'
      responses:
        '200':
          $ref: 'link.yaml#/components/responses/LinkDetails'
        '404':
          $ref: 'base.yaml#/components/responses/NotFound'

    delete:
      summary: Delete link
      description: Delete a specific link by its hash.
      operationId: deleteLink
      tags:
        - Link
      parameters:
        - $ref: 'link.yaml#/components/parameters/LinkHashParam'
      responses:
        '204':
          $ref: 'link.yaml#/components/responses/LinkDeleted'
        '404':
          $ref: 'base.yaml#/components/responses/NotFound'

  /sitemap:
    post:
      summary: Add Sitemap
      description: Add a new sitemap.
      operationId: addSitemap
      tags:
        - Sitemap
      requestBody:
        $ref: 'sitemap.yaml#/components/requestBodies/SitemapRequest'
      responses:
        '200':
          $ref: 'sitemap.yaml#/components/responses/SitemapProcessed'
        '400':
          $ref: 'base.yaml#/components/responses/BadRequest'
        '500':
          $ref: 'base.yaml#/components/responses/InternalServerError'