openapi: 3.0.0
info:
  version: "2"
  title: Redirects and Vanity URLs for Confluence
  description: (This document describes API version 2, which is implemented in the app's version 3.0.0+ !)
    Confluence Server app that allows you to create short URLs and vanity URLs as redirects, letting you
    choose the concrete URL you give out to customers. It also allows you to change those mappings afterwards, so you
    can stay flexible if you ever want to move things around.
  contact:
    name: resolution Reichert Network Solutions GmbH
    url: https://resolution.de
  license:
    name: PROPRIETARY
security:
  - basicAuth: []
  - sessionCookie: []
servers:
  - url: https://{confluenceHost}{confluenceContextPath}/rest/vanityurl-admin/2.0
    description: Your Confluence server with the app installed
    variables:
      confluenceHost:
        default: yourconfluence.com
        description: Your Confluence server's hostname
      confluenceContextPath:
        default: ""
        description: Your Confluence server's context path
tags:
  - name: Config
  - name: URLMappings
paths:
  "/reconfigure/config/admin":
    get:
      summary: Returns the current configuration
      description: Returns the root configuration object and the url mappings
      operationId: getConfig
      tags:
        - Config
      responses:
        "200":
          description: Config response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rootConfiguration"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorModel"
    put:
      summary: Replaces the current configuration with the given one
      description: Replaces the current configuration in the database with the given one.
        This is an expensive operation, so only use it for e.g. restoring a
        backup or similar
      operationId: putConfig
      tags:
        - Config
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/rootConfiguration"
        description: the new configuration to set in the database
        required: true
      responses:
        "200":
          description: The new configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rootConfiguration"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorModel"
  /urlmappings:
    get:
      summary: Retrieves all or filtered URL mappings
      description: Retrieves all URL mappings. You can also provide filters to only
        retrieve the matching mappings
      operationId: getUrlMappings
      tags:
        - URLMappings
      parameters:
        - name: shortUrl
          in: query
          description: Optional, if results should be filtered by shortUrl. Will look for
            exact matches.
          required: false
          schema:
            type: string
        - name: longUrl
          in: query
          description: Optional, if results should be filtered by longUrl. Will look for
            exact matches.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: URL mappings response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/urlMapping"
    post:
      summary: Creates a new URL mapping.
      description: Creates a new URL mapping. Short URL must be unique.
      operationId: postUrlMapping
      tags:
        - URLMappings
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/urlMappingFromUser"
        description: New URL mapping to create
        required: true
      responses:
        "200":
          description: New URL mapping created response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/urlMapping"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorModel"
  "/urlmappings/{id}":
    get:
      summary: Returns a single URL mapping
      description: Returns a single URL mapping based on its ID
      operationId: getUrlMappingById
      tags:
        - URLMappings
      parameters:
        - name: id
          in: path
          description: ID of urlMapping to fetch
          required: true
          schema:
            type: integer
            format: int32
      responses:
        "200":
          description: URL mapping response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/urlMapping"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorModel"
    put:
      summary: Replaces a single URL mapping with the given one
      description: Replaces a single URL mapping based on its ID with the one given in the
        request.
      operationId: putUrlMappingById
      tags:
        - URLMappings
      parameters:
        - name: id
          in: path
          description: ID of urlMapping to fetch
          required: true
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/urlMappingFromUser"
        description: URL mapping to replace the existing one with
        required: true
      responses:
        "200":
          description: URL mapping response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/urlMapping"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorModel"
    delete:
      summary: Deletes a single URL mapping
      description: Deletes a single URL mapping based on the ID supplied
      operationId: deleteUrlMappingById
      tags:
        - URLMappings
      parameters:
        - name: id
          in: path
          description: ID of URL mapping to delete
          required: true
          schema:
            type: integer
            format: int32
      responses:
        "204":
          description: Short URL deleted
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/errorModel"
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    sessionCookie:
      type: apiKey
      name: JSESSIONID
      in: cookie
  schemas:
    nullableString:
      description: Either a non-empty string or null (represents empty / unset property)
      type: string
      minLength: 1
      nullable: true
    rootConfiguration:
      description: The root configuration. Contains all admin settings, as well as all URL
        mappings (without access events)
      type: object
      required:
        - linkModificationUserGroup
      properties:
        linkModificationUserGroup:
          "$ref": "#/components/schemas/nullableString"
        queryForwardingMode:
          type: string
          enum:
            - ALL
            - UTM_ONLY
            - CUSTOM
            - NONE
        queryForwardingCustomRegex:
          "$ref": "#/components/schemas/nullableString"
        adminMode:
          type: boolean
          readOnly: true
    urlMapping:
      description: Represents a single URL mapping
      type: object
      required:
        - id
        - shortUrl
        - longUrl
      properties:
        id:
          type: integer
          format: int32
        shortUrl:
          type: string
        longUrl:
          type: string
        anchor:
          type: string
        note:
          type: string
        creationUserKey:
          type: string
        creationDate:
          type: integer
          format: int64
        lastModificationUserKey:
          type: string
        lastModificationDate:
          type: integer
          format: int64
    urlMappingFromUser:
      type: object
      required:
        - shortUrl
        - longUrl
      properties:
        shortUrl:
          type: string
        longUrl:
          type: string
        anchor:
          type: string
        note:
          type: string
    errorModel:
      description: In case of an application error (i.e. not Unauthorized etc, but rather
        semantic errors like duplicate short URL or invalid arguments), this
        represents the error and contains a human-readable error message
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: The internal error code
          type: integer
          format: int32
        message:
          description: The human-readable error message
          type: string
