api.yaml

openapi: "3.0.0"
info:
  title: "News"
  version: "1.0"
paths:
  /news:
    get:
      tags:
        - "News"
      summary: "Get a list of news articles"
      parameters:
        - $ref: "#/components/parameters/LimitInQuery"
        - $ref: "#/components/parameters/OffsetInQuery"
      responses:
        200:
          description: "List of news articles"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NewsArticlesListItem"
              example:
                - id: "1de0f659-eac6-4ca6-9a84-5812b7e43b0d"
                  headline: "6 Surprising Elon Musk Opinions on Cat Dresses"
                  datePublished: "2022-01-01T15:00:00+0000"
                  author:
                    id: "ab82bcea-f04e-45f9-8b4f-9645a5a401a0"
                    name: "John Doe"
                  revokeReason: null
                - id: "f701740c-4f6b-4ddb-a567-741d8aae23ba"
                  headline: "Cat Dresses: Dos and Don'ts"
                  datePublished: "2022-01-01T17:00:00+0000"
                  author:
                    id: "6da7e3d0-3e4b-4125-a087-d64b77fe8ba8"
                    name: "Jane Smith"
                  revokeReason: "Fake"
  /news/{newsArticleId}:
    get:
      tags:
        - "News"
      summary: "Get single news article by ID"
      parameters:
        - $ref: "#/components/parameters/NewsArticleIdInPath"
      responses:
        200:
          description: "A news article"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NewsArticle"
              example:
                id: "5149fec6-db96-446a-8c8a-f3414606e182"
                headline: "10 Cat Dresses Products Under $20 That Reviewers Love"
                datePublished: "2022-01-01T15:00:00+0000"
                author:
                  id: "6d521306-ba9d-4503-ba9f-1ef9c800db3c"
                  name: "John Doe"
                image:
                  url: "https://example.com/images/1234"
                  description: "The description of the image"
                  author: "Emma Brown"
                text: "Full text of the news article"
                revokeReason: null
        404:
          description: "News article not found"
  /news/{newsArticleId}/revoke:
    post:
      tags:
        - "News"
      summary: "Revoke the news article, i.e. hide it"
      parameters:
        - $ref: "#/components/parameters/NewsArticleIdInPath"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
              required:
                - reason
            example:
              reason: "Fake"
      responses:
        204:
          description: "The news article successfully revoked"
        403:
          description: "User has no permission of revoking a news article"
        404:
          description: "News article not found"
  /drafts:
    get:
      tags:
        - "Drafts"
      summary: "Get a list of drafts"
      parameters:
        - $ref: "#/components/parameters/LimitInQuery"
        - $ref: "#/components/parameters/OffsetInQuery"
      responses:
        200:
          description: "List of drafts"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/DraftsListItem"
              example:
                - id: "cd1169f4-7765-4f13-b8d4-2c0d7f0662e1"
                  newsArticleId: "2097f31a-e2ef-4fe4-897d-0a17930f9997"
                  headline: "14 Reasons You Can Blame the Recession on Cat Dresses"
                  createByUserId: "9059db82-164c-4a3f-a5a7-1b09f6df654d"
                  isPublished: false
                - id: "19a402a1-97c5-4d9d-900d-1cdc1f790b12"
                  newsArticleId: "b7983653-a4e8-4d65-94e6-90e6fad2fd6a"
                  headline: "How to Master Cat Dresses in 30 Days"
                  createByUserId: "0bcb5c59-e414-4fa2-ba31-1016b7f0dd96"
                  isPublished: false
    post:
      tags:
        - "Drafts"
      summary: "Create a draft for news article"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                newsArticleId:
                  type: string
                  nullable: true
              required:
                - newsArticleId
            examples:
              "Create a draft from scratch":
                value:
                  newsArticleId: null
              "Create a draft for a news article":
                value:
                  newsArticleId: "3ac7d6f2-dc9a-4657-8a45-f761bde612e9"
        required: true
      responses:
        200:
          description: "Draft successfully created"
          content:
            application/json:
              schema:
                type: object
                properties:
                  draftId:
                    type: string
                required:
                  - draftId
              example:
                draftId: "ba95c9bf-59f7-4a7f-b5d4-3b87e36b5e61"
        403:
          description: "User can't manage drafts"
        409:
          description: "There is another draft already"
          content:
            application/json:
              schema:
                type: object
                properties:
                  draftId:
                    type: string
                  createdBy:
                    type: object
                    properties:
                      userId:
                        type: string
                    required:
                      - userId
                required:
                  - createdBy
              examples:
                "For admin user":
                  description: "Since admin user can delete any draft to release locked editor, draftId is returned."
                  value:
                    draftId: "2b62cac3-c77a-44f9-a699-842654131ba7"
                    createdBy:
                      userId: "381e9d82-45b7-441c-af6e-d1536289944a"
                "For any other user":
                  description: "Non admin users can't manage drafts created by another users. Because of this there is no need to return draftId."
                  value:
                    createdBy:
                      userId: "de2c5cff-74ee-4eef-990a-9ad2c6ec0c70"
  /drafts/{draftId}:
    get:
      tags:
        - "Drafts"
      summary: "Get a draft by ID"
      parameters:
        - $ref: "#/components/parameters/DraftIdInPath"
      responses:
        200:
          description: "A draft"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Draft"
              example:
                id: "11f53a27-a677-4c9a-9c8b-ee45ece37d02"
                newsArticleId: "34f528c2-de03-4d35-a189-96d81d857c39"
                headline: "Top 15 Online Courses to Get Ahead in Cat Dresses"
                datePublished: "2022-01-01T15:00:00+0000"
                author:
                  id: "84a6a8f1-cd1d-44fd-8279-b4f574236743"
                  name: "John Doe"
                image:
                  url: "https://example.com/images/1234"
                  description: "The description of the image"
                  author: "Emma Brown"
                text: "Full text of the news article"
        403:
          description: "User can't manage drafts"
        404:
          description: "Draft not found"
    put:
      tags:
        - "Drafts"
      summary: "Update the draft with ID"
      parameters:
        - $ref: "#/components/parameters/DraftIdInPath"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                headline:
                  type: string
                datePublished:
                  type: string
                  nullable: true
                authorId:
                  type: string
                image:
                  type: object
                  nullable: true
                  properties:
                    url:
                      type: string
                    description:
                      type: string
                    author:
                      type: string
                  required:
                    - url
                    - description
                    - author
                text:
                  type: string
              required:
                - headline
                - datePublished
                - authorId
                - image
                - text
            example:
              headline: "The Ultimate Cat Dresses Checklist"
              datePublished: "2022-01-01T15:00:00+0000"
              authorId: "e2dac36e-4e61-4266-b888-b69741c10584"
              image:
                url: "https://example.com/images/1234"
                description: "The description of the image"
                author: "Emma Brown"
              text: "Full text of the news article"
      responses:
        204:
          description: "The draft is successfully updated"
        403:
          description: "User can't manage drafts"
        404:
          description: "Draft not found"
    delete:
      tags:
        - "Drafts"
      summary: "Delete the draft with ID"
      parameters:
        - $ref: "#/components/parameters/DraftIdInPath"
      responses:
        204:
          description: "The draft is successfully deleted"
        403:
          description: "User can't manage drafts"
        404:
          description: "Draft not found"
  /drafts/{draftId}/publish:
    post:
      tags:
        - "Drafts"
      summary: "Publish the draft with ID"
      parameters:
        - $ref: "#/components/parameters/DraftIdInPath"
      responses:
        200:
          description: "The draft is successfully published"
          content:
            application/json:
              schema:
                type: object
                properties:
                  newsArticleId:
                    type: string
                required:
                  - newsArticleId
              example:
                newsArticleId: "feca82f7-b268-446c-b7e0-e710a7e2ac51"
        403:
          description: "User can't publish drafts"
        404:
          description: "Draft not found"
        409:
          description: "Some requirements are not satisfied, can't publish"
          content:
            application/json:
              schema:
                type: object
                properties:
                  problems:
                    type: array
                    items:
                      type: object
                      properties:
                        message:
                          type: string
                        userMessage:
                          type: string
                      required:
                        - message
                        - userMessage
                required:
                  - problems
  /authors:
    get:
      tags:
        - "Authors"
      summary: "List authors"
      parameters:
        - $ref: "#/components/parameters/LimitInQuery"
        - $ref: "#/components/parameters/OffsetInQuery"
      responses:
        200:
          description: "List of authors"
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Author"
              example:
                - id: "8a8f776e-5f83-4265-b958-d85f50ed916c"
                  name: "John Doe"
                - id: "4f6823f6-e47b-4fa2-a966-ab6271451438"
                  name: "Jane Smith"
    post:
      tags:
        - "Authors"
      summary: "Create an author"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
                - name
            example:
              name: "John Doe"
      responses:
        201:
          description: "Author created successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  authorId:
                    type: string
                required:
                  - authorId
              example:
                authorId: "a32dc42c-c328-4917-bb54-df0ae0785614"
        403:
          description: "User can't manage authors"
  /authors/{authorId}:
    get:
      tags:
        - "Authors"
      summary: "Get an author by ID"
      parameters:
        - $ref: "#/components/parameters/AuthorIdInPath"
      responses:
        200:
          description: "An author"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Author"
              example:
                id: "2fdca7cb-7818-4110-ad54-b54e07f9ea2a"
                name: "John Doe"
        404:
          description: "Author not found"
    put:
      tags:
        - "Authors"
      summary: "Update the author with ID"
      parameters:
        - $ref: "#/components/parameters/AuthorIdInPath"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
              required:
                - name
            example:
              name: "John Doe"
      responses:
        204:
          description: "Author updated successfully"
        403:
          description: "User can't manage authors"
        404:
          description: "Author not found"
    delete:
      tags:
        - "Authors"
      summary: "Delete the author with ID"
      parameters:
        - $ref: "#/components/parameters/AuthorIdInPath"
      responses:
        204:
          description: "Author deleted successfully"
        403:
          description: "User can't manage authors"
        404:
          description: "Author not found"
        409:
          description: "Can't delete an author with at least one published news article"
  /authors/default:
    get:
      tags:
        - "Authors"
      summary: "Default author for user"
      parameters:
        - name: "user-id"
          in: query
          description: "ID of the user for which need to know default author. If this parameter is not set or is set to null, current user's ID will be used"
          schema:
            type: string
            nullable: true
          example: "66189e9c-3058-4477-87ad-548603608c84"
      responses:
        200:
          description: "Default author for the user"
          content:
            application/json:
              schema:
                type: object
                properties:
                  author:
                    type: object
                    nullable: true
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                    required:
                      - id
                      - name
                required:
                  - author
              examples:
                "Default author is NOT set":
                  value:
                    author: null
                "Default author is set":
                  value:
                    author:
                      id: "c5d0c70c-bcd9-4b1d-8d61-6d6a548556af"
                      name: "John Doe"
    put:
      tags:
        - "Authors"
      summary: "Set default author for user"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  nullable: true
                authorId:
                  type: string
                  nullable: true
              required:
                - userId
                - authorId
            examples:
              "For current user":
                value:
                  userId: null
                  authorId: "99bfd03c-40e4-416b-9d49-b5db31ec0fda"
              "For any user":
                value:
                  userId: "6beaf485-3663-494b-891f-7d769543f048"
                  authorId: "3aedc76d-65f7-4120-9cec-a15bed00b274"
      responses:
        204:
          description: "Default author set successfully"
        403:
          description: "User can't manage default authors"
        404:
          description: "Author not found"
tags:
  - name: "Authors"
  - name: "Drafts"
  - name: "News"
components:
  schemas:
    Author:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
    Draft:
      type: object
      properties:
        id:
          type: string
        newsArticleId:
          type: string
          nullable: true
        headline:
          type: string
        datePublished:
          type: string
          nullable: true
        author:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        image:
          type: object
          nullable: true
          properties:
            url:
              type: string
            description:
              type: string
            author:
              type: string
          required:
            - url
            - description
            - author
        text:
          type: string
        createdByUserId:
          type: string
        isPublished:
          type: boolean
      required:
        - id
        - newsArticleId
        - headline
        - datePublished
        - author
        - image
        - text
        - createdByUserId
        - isPublished
    DraftsListItem:
      type: object
      properties:
        id:
          type: string
        newsArticleId:
          type: string
          nullable: true
        headline:
          type: string
        createByUserId:
          type: string
        isPublished:
          type: boolean
      required:
        - id
        - newsArticleId
        - headline
        - createByUserId
        - isPublished
    NewsArticle:
      type: object
      properties:
        id:
          type: string
        headline:
          type: string
        datePublished:
          type: string
        author:
          $ref: "#/components/schemas/Author"
        image:
          type: object
          properties:
            url:
              type: string
            description:
              type: string
            author:
              type: string
          required:
            - url
            - description
            - author
        text:
          type: string
        revokeReason:
          type: string
          nullable: true
      required:
        - id
        - headline
        - datePublished
        - author
        - image
        - text
        - revokeReason
    NewsArticlesListItem:
      type: object
      properties:
        id:
          type: string
        headline:
          type: string
        datePublished:
          type: string
        author:
          $ref: "#/components/schemas/Author"
        revokeReason:
          type: string
          nullable: true
      required:
        - id
        - headline
        - datePublished
        - author
        - revokeReason
  parameters:
    NewsArticleIdInPath:
      name: "newsArticleId"
      in: path
      description: "ID of the news article"
      required: true
      schema:
        type: string
      example: "0a5f533f-83c9-4637-985f-645bc8bfe42b"
    DraftIdInPath:
      name: "draftId"
      in: path
      description: "ID of the draft"
      required: true
      schema:
        type: string
      example: "f52d64c2-97b2-4723-a70e-9f2e6784c75a"
    AuthorIdInPath:
      name: "authorId"
      in: path
      description: "ID of the author"
      required: true
      schema:
        type:
          string
      example: "49db2288-e874-4af6-bbcc-3b2de5d5fcd7"
    LimitInQuery:
      name: "limit"
      in: query
      description: "Max number of returned items, a.k.a. page size"
      schema:
        type: integer
      example: 10
    OffsetInQuery:
      name: "offset"
      in: query
      description: "Skip that many items before beginning to return items"
      schema:
        type: integer
      example: 30