swagger.yaml

swagger: '2.0'
info:
  title: CMS API
  description: CMS Page Metadata
  version: "1.0.0"
# the domain of the service
host: brands.zalando.net
basePath: /api
schemes:
  - https
produces:
  - application/json
securityDefinitions:
  api_key:
    type: apiKey
    name: x-api-token
    in: header
paths:
  "/pages":
    get:
      summary: Published CMS pages
      description: |
        The Pages endpoint returns information about the Brand Shop CMS
        pages the user has permission to view. The response contains an array
        of page objects.
      tags:
        - page
      responses:
        200:
          description: An array of pages
          schema:
            $ref: '#/definitions/PageCollection'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/ErrorCollection'
  "/pages/{pageId}":
    get:
      tags:
        - page
      summary: Get page by ID
      description: Returns a single page
      operationId: getPageById
      produces:
        - application/json
      parameters:
        - name: pageId
          in: path
          description: ID of page to return
          required: true
          type: integer
          format: int64
      responses:
        "200":
          description: Page found
          schema:
            $ref: "#/definitions/PageCollection"
        "404":
          description: Page not found
          schema:
            $ref: "#/definitions/ErrorCollection"
    put:
      tags:
        - page
      description: ""
      summary: Create or update a page
      operationId: createOrUpdatePage
      produces:
        - application/json
      parameters:
        - name: pageId
          in: path
          description: ID of page to be created or updated
          required: true
          type: integer
          format: int64
        - name: body
          in: body
          description: New or updated page
          required: true
          schema:
            $ref: '#/definitions/PageCollection'
      responses:
        200:
          description: "An existing Page was modified"
          schema:
            $ref: '#/definitions/PageCollection'
        201:
          description: "A new Page was created"
          schema:
            $ref: '#/definitions/PageCollection'
        409:
          description: "Invalid page"
          schema:
            $ref: '#/definitions/ErrorCollection'
  "/pages/{pageId}/insights/performance":
    get:
      tags:
      - performance
      description: ""
      operationId: "getPagePerformance"
      produces:
        - application/json
      parameters:
        - name: pageId
          in: path
          description: ID of page to be created or updated
          required: true
          type: integer
          format: int64
        - name: from
          in: query
          required: false
          type: string
          format: date
        - name: to
          in: query
          required: false
          type: string
          format: date
      responses:
        200:
          description: ""
          schema:
            $ref: '#/definitions/PagePerformanceCollection'
  "/pages/{pageId}/insights/performance/{date}":
    get:
      tags:
      - performance
      description: ""
      operationId: "getPagePerformance"
      produces:
        - application/json
      parameters:
        - name: pageId
          in: path
          description: ID of page to be created or updated
          required: true
          type: integer
          format: int64
        - name: date
          in: path
          description: Date to fetch performance for
          required: true
          type: string
          format: date
      responses:
        200:
          description: ""
          schema:
            $ref: '#/definitions/PagePerformanceCollection'
        404:
          description: ""
    put:
      tags:
      - performance
      produces:
        - application/json
      parameters:
        - name: pageId
          in: path
          description: ID of page to be created or updated
          required: true
          type: integer
          format: int64
        - name: date
          in: path
          description: Date to fetch performance for
          required: true
          type: string
          format: date
        - name: body
          in: body
          description: New performance record
          required: true
          schema:
            $ref: '#/definitions/PagePerformanceCollection'
      responses:
        200:
          description: ""
          schema:
            $ref: '#/definitions/PagePerformanceCollection'
        201:
          description: ""
          schema:
            $ref: '#/definitions/PagePerformanceCollection'
  "/pages/{pageId}/insights/interactions":
    get:
      tags:
      - interactions
      description: ""
      operationId: "getPageInteractions"
      produces:
        - application/json
      parameters:
        - name: pageId
          in: path
          description: ID of the page
          required: true
          type: integer
          format: int64
        - name: from
          in: query
          required: false
          type: string
          format: date
        - name: to
          in: query
          required: false
          type: string
          format: date
      responses:
        200:
          description: ""
          schema:
            $ref: '#/definitions/InteractionCollection'
        404:
          description: ""
          schema:
            $ref: '#/definitions/ErrorCollection'
  "/pages/{pageId}/insights/interactions/{date}":
    get:
      tags:
      - interactions
      description: ""
      operationId: "getPageInteractionsForDate"
      produces:
        - application/json
      parameters:
        - name: pageId
          in: path
          description: ID of page
          required: true
          type: integer
          format: int64
        - name: date
          in: path
          description: Date to fetch interactions for
          required: true
          type: string
          format: date
      responses:
        200:
          description: ""
          schema:
            $ref: '#/definitions/InteractionCollection'
        404:
          description: "Resource not found"
    put:
      tags:
      - interactions
      produces:
        - application/json
      parameters:
        - name: pageId
          in: path
          description: ID of page
          required: true
          type: integer
          format: int64
        - name: date
          in: path
          description: Date of interactions
          required: true
          type: string
          format: date
        - name: body
          in: body
          description: New interaction record
          required: true
          schema:
            $ref: '#/definitions/InteractionCollection'
      responses:
        200:
          description: "The record was updated."
          schema:
            $ref: '#/definitions/InteractionCollection'
        201:
          description: "The record was created."
          schema:
            $ref: '#/definitions/InteractionCollection'
        400:
          description: "The record is invalid."
          schema:
            $ref: '#/definitions/ErrorCollection'
        404:
          description: "The page does not exist."
          schema:
            $ref: '#/definitions/ErrorCollection'
definitions:
  PageCollection:
    properties:
      data:
        type: array
        items: 
          $ref: '#/definitions/Page'
  Page:
    type: object
    required: ["id", "path", "app-domain-id", "target-group-id", "name", "brand", "updates"]
    properties:
      id:
        type: integer
        format: int64
      path:
        type: string
      app-domain-id:
        type: integer
        format: int64
      target-group-id:
        type: integer
        format: int64
      name:
        type: string
      brand:
        type: string
      updates:
        type: array
        items:
          type: string
          format: date-time
  PagePerformanceCollection:
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/PagePerformance'
  PagePerformance:
    properties:
      date:
        type: string
        format: date-time
      views:
        type: integer
        format: int32
      unique-views:
        type: integer
        format: int32
      entrances:
        type: integer
        format: int32
      exits:
        type: integer
        format: int32
      average-time-on-page:
        type: string
      entrance-rate:
        type: number
        format: float
      exit-rate:
        type: number
        format: float
      bounces:
        type: integer
        format: int32
      conversion-rate:
        type: number
        format: float
      engagement-rate:
        type: number
        format: float
  InteractionCollection:
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Interaction'
  Interaction:
    properties:
      element:
        type: object
        properties:
          name:
            type: string
          type:
            type: string
      action:
        type: string
        enum: ['click']
      category:
        type: string
      total-occurrences:
        type: integer
        format: int32
      total-value:
        type: number
        format: float
      unique-occurrences:
        type: integer
        format: int32
      sessions-with-interaction:
        type: integer
        format: int32
  ErrorCollection:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/Error'
  Error:
    type: object
    properties:
      id:
        type: integer
        format: int64
      href:
        type: string
        format: url
      status:
        type: integer
        format: int32
      code:
        type: string
      title:
        type: string
      detail:
        type: string
      links:
        type: array
        items:
          type: string
      paths:
        type: array
        items:
          type: string