Content Comparison

swagger: "2.0"
info:
  version: "0.0.1"
  title: ARES Kudo API server
# during dev, should point to your local machine
host: localhost:3000
# basePath prefixes all resource paths 
basePath: /api
# 
tags:
  - name: ARES Kudo Required
    description: Required APIs to load and store a drawing
  - name: ARES Kudo Optional
    description: Optional APIs to improve interactions for loading and storing a drawing
  - name: File Sessions
    description: Optional File Session Handling (has to be implemented if sessionId query parameter is passed to editor url)
  - name: Commenting
    description: API support for commenting panel
  - name: User Sessions
    description: Optional User Session Handling (has to be implemented if sessionId query parameter is passed to editor url)
    
schemes:
  # tip: remove http to make production-grade
  - http
  - https
# format of bodies a client can send (Content-Type)
consumes:
  - application/json
# format of the responses to the client (Accepts)
produces:
  - application/json
parameters:
  fileId:
    name: fileId
    in: path
    description: The id of the file
    required: true
    type: string
  sessionId:
    name: sessionId
    in: header
    description: the user sessionId
    required: true
    type: string
  threadId:
    name: threadId
    in: path
    description: the comment thread
    required: true
    type: string
  markupId:
    name: markupId
    in: path
    description: the markup
    required: true
    type: string
  commentId:
    name: commentId
    in: path
    description: the comment
    required: true
    type: string
  attachmentId:
    name: attachmentId
    in: path
    description: the attachment
    required: true
    type: string
  optionalSessionId:
    name: sessionId
    in: header
    description: the user sessionId (optional; sent only if sessionId query parameter was passed to editor url)
    required: false
    type: string
  fileSessionId:
    name: xSessionId
    in: header
    description: the file sessionId
    required: true
    type: string
paths:
  /files/{fileId}/diffs:
    parameters:
      - $ref: '#/parameters/fileId'
      - $ref: '#/parameters/optionalSessionId'
    # binds a127 app logic to a route
    x-swagger-router-controller: files

    get:
      description: Returns file content
      # used as the method name of the controller
      operationId: diffs_get
      tags:
        - ARES Kudo Required
      responses:
        "200":
          description: Success
          schema:
            required:
              - status
              - baseContent
            properties:
              status: 
                type: string
                default: "ok"
              baseContent:
                type: string
                description: Base64 encoded content of file
                # responses may fall through to errors
        "404":
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
    put:
      description: Update file content
      # used as the method name of the controller
      operationId: diffs_put
      tags:
        - ARES Kudo Required
      parameters:
        - name: body
          in: body
          required: true
          schema:
            required:
              - baseContent
            properties:
              baseContent:
                type: string
                description: Base64 encoded content of file            

      responses:
        "200":
          description: Success
          schema:
            required:
              - status
              - changeId
            properties:
              status: 
                type: string
                default: "ok"
              changeId:
                type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /files:
    post:
      description: Create a new file
      # used as the method name of the controller
      operationId: post_file
      tags:
        - ARES Kudo Optional
      consumes:
         - multipart/form-data
      parameters:
        - in: header
          name: folderId
          required: true
          type: string
        - in: formData
          name: file
          required: true
          type: file
      responses:
        "200":
          description: Success
          schema:
            required:
              - status
              - changeId
            properties:
              status: 
                type: string
                default: "ok"
              changeId:
                type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /files/{fileId}/xref/search:
    # binds a127 app logic to a route
    x-swagger-router-controller: files
    post:
      description: XRef search
      # used as the method name of the controller
      operationId: xref_search
      tags:
        - ARES Kudo Optional
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/optionalSessionId'
        - name: body
          in: body
          required: true
          schema:
            required:
              - path
            properties:
              path:
                type: array
                description: xrefs paths to search            
                items: 
                  type: string
      responses:
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              result:
                type: array
                items:
                  type: object
                  properties:
                    path: 
                      type: string
                    files:
                      type: array
                      items:
                        type: object
                        properties:
                          "_id":
                            type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /files/{fileId}/preview:
    # binds a127 app logic to a route
    x-swagger-router-controller: files
    post:
      description: Optionally handle receiving updates previews
      # used as the method name of the controller
      operationId: preview_post
      tags:
        - ARES Kudo Optional
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/optionalSessionId'
      responses:
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
                        
  /files/{fileId}/info:
    # binds a127 app logic to a route
    x-swagger-router-controller: files
    get:
      description: Returns file information
      # used as the method name of the controller
      operationId: info_get
      tags:
        - ARES Kudo Required
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/optionalSessionId'
      responses:
        "200":
          description: Success
          schema:
            required:
              - status
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              filename: 
                type: string
              folderId: 
                type: string
              owner: 
                type: string
        # responses may fall through to errors
        "401":
          description: User is not autenticated
          schema:
            $ref: "#/definitions/ErrorResponse"
        "404":
          description: File is not found
          schema:
            $ref: "#/definitions/ErrorResponse"
  /files/{fileId}/session:
    # binds a127 app logic to a route
    parameters:
      - $ref: '#/parameters/fileId'
      - $ref: '#/parameters/optionalSessionId'

    x-swagger-router-controller: files
    get:
      description: get file sessions
      # used as the method name of the controller
      operationId: session_get
      tags:
        - File Sessions
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/SessionsResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
    post:
      description: Create file session. Sessions need to be either of type "view" or "edit"
      # used as the method name of the controller
      operationId: session_post
      tags:
        - File Sessions
      parameters:
        - name: body
          in: body
          required: true
          schema:
            required:
              - mode
            properties:
              mode:
                type: string
                description: Type of session requested   
                enum: [view, edit]
              fileId:
                type: string
                description: fileId for the file for which the session is being requested    
      responses:
        "200":
          description: Success
          schema:
            required:
              - status
              - "_id"
            properties:
              status: 
                type: string
                default: "ok"
              "_id":
                type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
    delete:
      description: delete file session
      # used as the method name of the controller
      operationId: session_delete
      tags:
        - File Sessions
      parameters:
        - $ref: '#/parameters/fileSessionId'
      responses:
        "200":
          description: Success
          schema:
            # a pointer to a definition
            $ref: "#/definitions/SessionsResponse"
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
  /auth:
    # binds a127 app logic to a route
    x-swagger-router-controller: auth
    get:
      description: validate user session
      # used as the method name of the controller
      tags:
        - User Sessions
      operationId: auth_get
      parameters:
        - $ref: '#/parameters/sessionId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
        401:
          description: Authorization information is missing or invalid.
  /users:
    # binds a127 app logic to a route
    x-swagger-router-controller: users
    get:
      description: Returns user object
      # used as the method name of the controller
      operationId: users_get
      tags:
        - User Sessions
      parameters:
        - $ref: '#/parameters/sessionId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              results:
                type: array
                items: 
                    type: object
                    properties:
                      fname:
                        type: string
                        description: first name
                      surname:
                        type: string
                        description: last name of user
                      "_id":
                        type: string
                      email:
                        type: string
                      licenseExpirationDate:
                        type: integer
                      preferences:
                        type: object
                        properties:
                          preferences_display:
                            type: object
                            properties: 
                              graphicswinmodelbackgrndcolor:
                                type: string
                                default: White
                          window:
                            type: object
                            properties:
                              edit:
                                type: object
                              view:
                                type: object
                          variables:
                            type: object
                            properties: 
                              dynasnap:
                                type: string
                                default: "63"
    put:
      description: Returns user object
      # used as the method name of the controller
      operationId: users_put
      tags:
        - User Sessions
      parameters:
        - $ref: '#/parameters/sessionId'
        - name: body
          in: body
          required: true
          schema:
            properties:
              preferences:
                type: object
                description: user preferences
                properties:
                  window:
                    type: object
                    properties:
                      edit:
                        type: object
                        properties:
                          dockwidgets:
                            type: object
                            properties:
                              layerwindow:
                                type: object
                                properties:
                                  h:
                                    type: string
                                    description: height o the layerwindow

      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
  /v1/files/{fileId}/annotations:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    get:
      description: Returns annotations for a file
      # used as the method name of the controller
      operationId: annotations_get
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - name: timestamp
          type: integer
          in: query
          required: false
          description: timestamp of last request to only send new items
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              results:
                type: object
                properties:
                  timestamp:
                    type: integer
                    description: time of response
 
                commmentThreads:
                    type: array
                    description: ""
                    items:
                      type: object
                  markups:
 
                  type: array
 
                  description: ""
                    items:
 
                    type: object
                  status:
                    type: string
                    default: "ok"
  /v1/files/{fileId}/markups:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    get:
      description: Returns markups for a file
      # used as the method name of the controller
      operationId: markups_get
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - name: timestamp
          type: integer
          in: query
          required: false
          description: timestamp of last request to only send new items
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              results:
                type: object
                properties:
                  timestamp:
                    type: integer
                    description: time of response
                  markups:
                    type: array
                    description: ""
                    items:
                      type: object
                  status:
                    type: string
                    default: "ok"

  /v1/files/{fileId}/commentThread:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    post:
      description: Add a new commentThread for a file
      # used as the method name of the controller
      operationId: commentThread_post
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - name: body
          in: body
          required: true
          schema: 
            type: object
            properties:
              title:
                type: string
              text:
                type: string
              state:
                type: string
                enum: [ACTIVE, RESOLVED]
              ids:
                type: array
                items:
                  type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/commentThread/{threadId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    put:
      description: Update a commentThread 
      # used as the method name of the controller
      operationId: commentThread_put
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/threadId'
        - name: body
          in: body
          required: true
          schema: 
            type: object
            properties:
              title:
                type: string
              text:
                type: string
              ids:
                type: array
                items:
                  type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    get:
      description: get a commentThread 
      # used as the method name of the controller
      operationId: commentThread_get
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/threadId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response  
  /v1/files/{fileId}/commentThread/{threadId}/comment/{commentId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    put:
      description: Update a comment 
      # used as the method name of the controller
      operationId: comment_put
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/threadId'
        - $ref: '#/parameters/commentId'
        - name: body
          in: body
          required: true
          schema: 
            type: object
            properties:
              text:
                type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    get:
      description: Retrieve a comment 
      # used as the method name of the controller
      operationId: comment_get
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/threadId'
        - $ref: '#/parameters/commentId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    delete:
      description: Delete a comment 
      # used as the method name of the controller
      operationId: comment_delete
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/threadId'
        - $ref: '#/parameters/commentId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/commentThread/{threadId}/comment:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    post:
      description: Post a new comment 
      # used as the method name of the controller
      operationId: comment_post
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/threadId'
        - name: body
          in: body
          required: true
          schema: 
            type: object
            properties:
              text:
                type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/markup:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    post:
      description: Add a new markup for a file
      # used as the method name of the controller
      operationId: markup_post
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - name: body
          in: body
          required: true
          schema: 
            type: object
            properties:
              title:
                type: string
              text:
                type: string
              state:
                type: string
                enum: [ACTIVE, RESOLVED]
              ids:
                type: array
                items:
                  type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/markup/{markupId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    put:
      description: Update a markup 
      # used as the method name of the controller
      operationId: markup_put
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/markupId'
        - name: body
          in: body
          required: true
          schema: 
            type: object
            properties:
              title:
                type: string
              text:
                type: string
              ids:
                type: array
                items:
                  type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    get:
      description: get a markup 
      # used as the method name of the controller
      operationId: markup_get
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/markupId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response  
    delete:
      description: delete a markup 
      # used as the method name of the controller
      operationId: markup_delete
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/markupId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response  
  /v1/files/{fileId}/markup/{markupId}/comment/{commentId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    put:
      description: Update a comment 
      # used as the method name of the controller
      operationId: markupcomment_put
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/markupId'
        - $ref: '#/parameters/commentId'
        - name: body
          in: body
          required: true
          schema: 
            type: object
            properties:
              text:
                type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    get:
      description: Retrieve a markup comment 
      # used as the method name of the controller
      operationId: markupcomment_get
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/markupId'
        - $ref: '#/parameters/commentId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
    delete:
      description: Delete a markup comment 
      # used as the method name of the controller
      operationId: markupcomment_delete
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/markupId'
        - $ref: '#/parameters/commentId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/markup/{markupId}/comment:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    post:
      description: Post a new markup comment 
      # used as the method name of the controller
      operationId: markupcomment_post
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/markupId'
        - name: body
          in: body
          required: true
          schema: 
            type: object
            properties:
              text:
                type: string
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/attachments:
    post:
      description: Create a markup attachment
      # used as the method name of the controller
      operationId: post_markup
      tags:
        - Commenting
      consumes:
         - multipart/form-data
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - in: formData
          name: file
          required: true
          type: file
      responses:
        "200":
          description: Success
          schema:
            required:
              - status
              - changeId
            properties:
              status: 
                type: string
                default: "ok"
              changeId:
                type: string
        # responses may fall through to errors
        default:
          description: Error
          schema:
            $ref: "#/definitions/ErrorResponse"
    get:
      description: Retrieve all attachments 
      # used as the method name of the controller
      operationId: attachments_get
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /v1/files/{fileId}/attachments/{attachmentId}:
    # binds a127 app logic to a route
    x-swagger-router-controller: comments
    get:
      description: Retrieve attachment 
      # used as the method name of the controller
      operationId: attachment_get
      tags:
        - Commenting
      parameters:
        - $ref: '#/parameters/fileId'
        - $ref: '#/parameters/sessionId'
        - $ref: '#/parameters/attachmentId'
      responses:
        # responses may fall through to errors
        "200":
          description: Success
          schema:
            type: object
            properties:
              status: 
                type: string
                default: "ok"
              timestamp:
                type: integer
                description: time of response
  /swagger:
    x-swagger-pipe: swagger_raw
# complex objects have schema definitions
definitions:
  SessionsResponse:
    required:
      - status
      - results
    properties:
      status: 
        type: string
        default: "ok"
      results:
        type: array
        items: 
            type: object
            properties:
              mode:
                type: string
                enum: [view, edit]
              username:
                type: string
              sessionId:
                type: string
              userId:
                type: string

  ErrorResponse:
    required:
      - message
    properties:
      message:
        type: string
      errrorId:
        type: string