api.yml

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Applifting Blog Engine
  description: >-
    This OpenAPI specification describes APIs available in the Applifing Blog Engine application.


    **Following APIs are exposed:**

    - Authentication - This API is used for login and access token acquisition

    - Blog - This API is a CRUD over blog entries

    - Comments - This API is used for comment creation and voting

    - Image - This API serves as an image store. It is assumed that images are uploaded during article creation.

    - Multitenancy - This API allows multiple blog instances to be active in a single application.


    **Authorization**


    All APIs except the Multitenancy API, are protected using API-KEY Token,
    which has either been given to the candidate during the exercise introduction or the candidate can create
    it themselves using the Multitenancy API `POST /tenants` endpoint. If you were already given a token, please prefer 
    to use it instead of creating a new one.  
    API-KEY Token MUST be sent like so `X-API-KEY: my-x-api-key` in the HTTP header.


    Comments, Blog and Images APIs are also protected using the Access Token acquired from the `/login` EndPoint.
    Access Token MUST be sent like so `Authorization: my-access-token` in the HTTP header.
servers:
  - url: https://fullstack.exercise.applifting.cz
paths:
  /login:
    post:
      summary: Sign in into the application
      security:
        - ApiKeyAuth: []
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - password
              properties:
                username:
                  type: string
                password:
                  type: string
                  format: password

      responses:
        "201":
          description: Access token detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccessToken"
        "400":
          description: Invalid login credentials
          content:
            application/json:
              example:
                code: INVALID_CREDENTIALS
                message: Password is invalid
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"

  /articles:
    get:
      summary: List of all articles
      operationId: listArticles
      tags:
        - Blog
      parameters:
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/limit"
      responses:
        "200":
          description: Article list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Article"
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"

    post:
      summary: Create an article
      operationId: createArticle
      tags:
        - Blog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArticleDetail"
      responses:
        "200":
          description: Detail of the created article
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleDetail"
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"
        "403":
          $ref: "#/components/responses/UnauthorizedError"

  /articles/{articleId}:
    get:
      summary: Article detail with content and comments
      operationId: getArticle
      tags:
        - Blog
      parameters:
        - $ref: "#/components/parameters/articleId"
      responses:
        "200":
          description: Article detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleDetail"
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"

    patch:
      summary: Update article detail
      operationId: updateArticle
      tags:
        - Blog
      parameters:
        - $ref: "#/components/parameters/articleId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArticleDetail"
      responses:
        "200":
          description: Updated article detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArticleDetail"
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"
        "403":
          $ref: "#/components/responses/UnauthorizedError"

    delete:
      summary: Delete article
      operationId: deleteArticle
      tags:
        - Blog
      parameters:
        - $ref: "#/components/parameters/articleId"
      responses:
        "204":
          description: Article no longer exists
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"
        "403":
          $ref: "#/components/responses/UnauthorizedError"

  /comments:
    post:
      summary: Create comment
      tags:
        - Comments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Comment"

      responses:
        "201":
          description: Detail of the created comment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"

  /comments/{commentId}/vote/up:
    post:
      summary: Upvote comment
      tags:
        - Comments
      parameters:
        - $ref: "#/components/parameters/commentId"
      responses:
        "201":
          description: Updated comment detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"

  /comments/{commentId}/vote/down:
    post:
      summary: Downvote comment
      tags:
        - Comments
      parameters:
        - $ref: "#/components/parameters/commentId"
      responses:
        "201":
          description: Updated comment detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Comment"
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"

  /images:
    post:
      summary: Upload an image
      tags:
        - Images
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: array
                  items:
                    type: string
                    format: binary

      responses:
        "201":
          description: Image uploaded successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ImageInfo"
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"

  /images/{imageId}:
    get:
      summary: Download image
      tags:
        - Images
      parameters:
        - $ref: "#/components/parameters/imageId"
      responses:
        "200":
          description: Image file
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"
          
    delete:
      summary: Delete image
      tags:
        - Images
      parameters:
        - $ref: "#/components/parameters/imageId"
      responses:
        "204":
          description: Image no longer exists
        "401":
          $ref: "#/components/responses/ApiKeyInvalidError"

  /tenants:
    post:
      summary: Create tenant
      security: []
      tags:
        - Multitenancy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Tenant"

      responses:
        "201":
          description: Detail of the created tenant
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tenant"

  /tenants/{tenantId}:
    get:
      summary: Info for a specific tenant
      security: []
      tags:
        - Multitenancy
      parameters:
        - $ref: "#/components/parameters/tenantId"
      responses:
        "200":
          description: Tenant detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tenant"

components:
  parameters:
    tenantId:
      name: tenantId
      in: path
      required: true
      description: Id of the tenant to retrieve
      schema:
        type: string
        format: uuid
    imageId:
      name: imageId
      in: path
      required: true
      description: Id of the image to retrieve
      schema:
        type: string
        format: uuid
    articleId:
      name: articleId
      in: path
      required: true
      description: Id of an article
      schema:
        type: string
        format: uuid
    commentId:
      name: commentId
      in: path
      required: true
      description: Id of an comment
      schema:
        type: string
        format: uuid
    offset:
      name: offset
      in: query
      required: false
      description: Number of items to skip during pagination
      schema:
        default: 0
        minimum: 0
        type: number
    limit:
      name: limit
      in: query
      required: false
      description: >-
        Number of items to return per page.
        All items are returned if `limit` is omitted.
      schema:
        minimum: 0
        type: number

  securitySchemes:
    BearerAuth:
      description: Access token acquired from the /login call
      type: http
      scheme: bearer
    ApiKeyAuth:
      description: API key for multitenancy
      type: apiKey
      in: header
      name: X-API-KEY

  responses:
    ApiKeyInvalidError:
      description: API key is missing or invalid
      content:
        application/json:
          example:
            code: API_KEY_INVALID
            message: API key missing or invalid
    UnauthorizedError:
      description: Access token is missing or invalid
      content:
        application/json:
          example:
            code: UNAUTHORIZED
            message: Access token is missing, invalid or expired

  schemas:
    Pagination:
      type: object
      properties:
        offset:
          type: number
          description: Number of items skipped during pagination
        limit:
          type: number
          description: Number of items returned
        total:
          type: number
          description: Total number of items
    ArticleList:
      type: object
      properties:
        pagination:
          $ref: "#/components/schemas/Pagination"
        items:
          type: array
          items:
            $ref: "#/components/schemas/Article"
    Article:
      type: object
      properties:
        articleId:
          type: string
          format: uuid
        title:
          type: string
          example: Lorem Ipsum
        perex:
          type: string
          example: Lorem Ipsum is simply dummy text of the printing and typesetting industry.
        imageId:
          type: string
          format: uuid
        createdAt:
          readOnly: true
          type: string
          format: date-time
        lastUpdatedAt:
          readOnly: true
          type: string
          format: date-time
    ArticleDetail:
      allOf:
        - $ref: "#/components/schemas/Article"
        - type: object
          properties:
            content:
              type: string
              format: markdown
              example: >
                # Lorem Ipsum

                **Lorem Ipsum** is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged.
            comments:
              type: array
              readOnly: true
              items:
                $ref: "#/components/schemas/Comment"
    Comment:
      type: object
      required:
        - articleId
        - author
        - content
      properties:
        commentId:
          type: string
          format: uuid
          readOnly: true
        articleId:
          type: string
          format: uuid
        author:
          type: string
          example: Jan Novak
        content:
          type: string
          example: This article is on point and very inspirational.
        postedAt:
          type: string
          format: date-time
          readOnly: true
        score:
          type: integer
          example: 42
          readOnly: true
    ImageInfo:
      type: object
      required:
        - imageId
      properties:
        imageId:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          example: "screenshot.png"
    Tenant:
      type: object
      properties:
        tenantId:
          type: string
          format: uuid
          readOnly: true
        apiKey:
          type: string
          format: uuid
          description: API key to be used in the `api-key` header
          readOnly: true
        name:
          type: string
          description: Human readable name of the tenant
          example: Jan Novak
        password:
          type: string
          format: password
          description: Authentication password of the tenant
          example: correct horse battery staple
          writeOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
        lastUsedAt:
          type: string
          format: date-time
          readOnly: true
    AccessToken:
      type: object
      properties:
        access_token:
          type: string
          description: Use this when requesting authenticated API endpoints
          format: uuid
          readOnly: true
        expires_in:
          type: integer
          description: Number of seconds before the access_token expires
          readOnly: true
          example: 3600
        token_type:
          type: string
          description: Token type. Will always be bearer
          example: bearer

security:
  - ApiKeyAuth: []
  - BearerAuth: []