databag/api.oa3

openapi: 3.0.0
info:
  description: |
    DataBag provides storage for decentralized identity based self-hosting apps.
    It is intended to support sharing of personal data and hosting group
    conversations.
  version: "0.0.1"
  title: DataBag
  termsOfService: 'http://swagger.io/terms/'
  contact:
    email: roland.osborne@gmail.com
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
  - name: revision
    description: websocket endpoint for receiving module revision events
  - name: admin
    description: account creation for portal backend.
  - name: account
    description: account configuration for portal backend. supports app attachment
  - name: authenticate
    description: authenticate holder of identity for external service
  - name: profile
    description: getting and setting of the public profile
  - name: contact
    description: connection to other identities, hook receiver
    
  - name: content
    description: posting and listing of personal subjects, group and tag managment
  - name: sharing
    description: sharing personal subjects, associates content and contacts
  - name: converstaion
    description: group sharing of subjects
    
paths:

  /revision:
    get:
      tags:
        - revision
      description: Websocket placeholder endpoint for receiving revision updates
      operationId: websocket
      responses:
        '200':
          description: Awaiting announce
        
  /admin/claimable:
    get:
      tags:
        - admin
      description: Check if portal params have been set
      operationId: node-configurable
      responses:
        '200':
          description: success
        '405':
          description: admin already configured
        '500':
          description: internal server error
          
  /admin/config:
    post:
      tags:
        - admin
      description: Set admin password and node domain
      operationId: add-node-config
      security:
        - basicAuth: []
      parameters:
        - name: domain
          in: query
          description: domain of node
          required: true
          schema:
            type: string
      responses:
        '200':
          description: success
        '405':
          description: admin already configured
        '500':
          description: internal server error
          
  /admin/config/domain:
    put:
      tags:
        - admin
      description: Set portal domain
      operationId: set-node-config-domain
      security:
        - basicAuth: []
      responses:
        '200':
          description: success
        '401':
          description: authentication error
        '500':
          description: internal server error
      requestBody:
        content:
          application/json:
            schema:
              type: string
          
  /admin/token:
    put:
      tags:
        - admin
      description: Create password reset token url
      operationId: set-node-account
      security:
        - basicAuth: []
      parameters:
        - name: guid
          in: query
          description: id of profile to access
          required: true
          schema:
            type: string
      responses:
        '201':
          description: generated
          content:
            application/json:
              schema:
                type: string
        '401':
          description: invalid password
        '404':
          description: unknown portal
        '500':
          description: internal server error
    post:
      tags:
        - admin
      description: Create new account token url
      operationId: add-node-account
      security:
        - basicAuth: []
      responses:
        '201':
          description: generated
          content:
            application/json:
              schema:
                type: string
        '401':
          description: invalid password
        '500':
          description: internal server error
          
  /admin/accounts:
    get:
      tags:
        - admin
      description: Get list of portals
      operationId: get-node-accounts
      security:
        - basicAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProfileView'
        '401':
          description: invalid password
        '404':
          description: handle not found
        '500':
          description: internal server error
          
  /admin/accounts/{guid}:
    delete:
      tags:
        - admin
      description: Remove account from node
      operationId: remove-node-account
      security:
        - basicAuth: []
      parameters:
        - name: guid
          in: path
          description: id of account to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '401':
          description: invalid authentication
        '404':
          description: account not found
        '500':
          description: internal server error
        
  /admin/accounts/{guid}/image:
    get:
      tags:
        - admin
      description: Get  profile of specified account
      operationId: get-node-account-image
      security:
        - basicAuth: []
      parameters:
        - name: guid
          in: path
          description: id of specified account
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: invalid password
        '404':
          description: account not found
        '500':
          description: internal server error
          
  /account/claimable:
    get:
      tags:
        - account
      description: Check if username is available
      operationId: check-username
      security:
        - bearerAuth: []
      parameters:
        - name: username
          in: query
          description: username to check 
          required: true
          schema:
            type: string
      responses:
        '200':
          description: success
        '401':
          description: authentication error
        '405':
          description: username already taken
        '500':
          description: internal server error
          
  /account/token:
    get:
      tags:
        - account
      description: Check if bearer token is valid
      operationId: check-token
      security:
        - bearerAuth: []
      responses:
        '200':
          description: success
        '401':
          description: invalid token
        '500':
          description: internal server error
          
  /account/profile:
    get:
      tags:
        - account
      description: Get public profile object
      operationId: get-account-profile
      security:
        - basicAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '401':
          description: authentication error
        '500':
          description: internal server error
    post:
      tags:
        - account
      description: Add a new account
      operationId: add-account
      security:
        - bearerAuth: []
        - basicAuth: []
      responses:
        '201':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
        '400':
          description: invalid handle or password
        '401':
          description: invalid bearer token
        '500':
          description: internal server error
                
  /account/authentication:
    post:
      tags:
        - account
      description: Generate token to reset authentication
      operationId: add-account-authentication
      security:
        - basicAuth: []
      responses:
        '201':
          description: generated
          content:
            application/json:
              schema:
                type: string
        '401':
          description: invalid password
        '500':
          description: internal server error
    put:
      tags:
        - account
      description: Apply account reset token to set handle and password
      operationId: set-account-authentication
      security:
        - bearerAuth: []
        - basicAuth: []
      responses:
        '201':
          description: successful operation
        '401':
          description: invalid token
        '406':
          description: invalid handle or password
        '500':
          description: internal server error
          
  /account/attachment:
    post:
      tags:
        - account
      description: Generate token to attach an app to the account
      operationId: add-account-app
      security:
        - basicAuth: []
      responses:
        '201':
          description: generated
          content:
            application/json:
              schema:
                type: string
        '401':
          description: invalid password
        '500':
          description: internal server error
    put:
      tags:
        - account
      description: Apply the app token and attach an app to the account
      operationId: set-account-app
      security:
        - bearerAuth: []
      responses:
        '201':
          description: generated
          content:
            application/json:
              schema:
                type: string
        '401':
          description: invalid token
        '406':
          description: app limit reached
        '500':
          description: internal server error
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppData'
          
  /account/apps:
    get:
      tags:
        - account
      description: Get list of attached apps
      operationId: get-account-apps
      security:
        - basicAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/App'
        '401':
          description: invalid password
        '500':
          description: internal server error
          
  /account/apps/{appId}:
    delete:
      tags:
        - account
      description: Get list of attached apps
      operationId: remove-account-app
      security:
        - basicAuth: []
      parameters:
        - name: appId
          in: path
          description: specified app id 
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '401':
          description: invalid password
        '404':
          description: app not found
        '500':
          description: internal server error
                  
  /authenticate:
    put:
      tags:
        - authenticate
      description: Sign payload containing external token for authentication
      operationId: authenticate
      security:
        - bearerAuth: []
      parameters:
        - name: token
          in: query
          description: token to sign in message response
          required: true
          schema:
            type: string
      responses:
        '201':
          description: generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataMessage'
        '401':
          description: invalid token
        '500':
          description: internal server error
          
  /profile:
    get:
      tags:
        - profile
      description: Get profile view object
      operationId: get-profile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileView'
        '401':
          description: invalid token
        '500':
          description: internal server error
    put:
      tags:
        - profile
      description: Set profile data
      operationId: set-profile
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
        '401':
          description: invalid token
        '500':
          description: internal server error
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileData'
          
  /profile/image:
    get:
      tags:
        - profile
      description: Get profile image
      operationId: get-profile-image
      security:
        - bearerAuth: []
      responses:
        '200':
          description: successful operation
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: invalid token
        '500':
          description: internal server error
          
  /profile/message:
    get:
      tags:
        - profile
      description: Get profile message
      operationId: get-profile-message
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataMessage'
        '401':
          description: invalid token
        '500':
          description: internal server error
          
  ## Contact Module: maintain 3 lists
  ### contacts: { disconnected, connecting, connected }
  ### blocked: any id on blocked list is silently ignored
  ### pending: limit number of pending contacts, created with Connect DataMessage
  
  # get list of contacts
  # add contact
  # remove contact
  # set contact disconnected
  # set contact connecting
  # set contact connected (apply token)
  # get connect message
  # get disconnect message
  # set connect message, if not contact adds to pending
  # set disconnect message
  # set pending to add contact with request
  # clear pending to ignore request
  # add blocked to block contact
  # remove blocked to unblock contact
  # get content&conversation revision
  # get contact content&conversation revision
  # set contact content&conversation revision
  
          
externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'

components:
  schemas:
  
    Announce:
      type: object
      required:
        - appToken
      properties:
        appToken:
          type: string
          
    Revsion:    
      type: object
      required:
        - profile
        - content
        - labels
        - sharing
        - contact
        - dialogue
        - insight
      properties:
        profile:
          type: integer
          format: int64
        content:
          type: integer
          format: int64
        labels:
          type: integer
          format: int64
        sharing:
          type: integer
          format: int64
        contact:
          type: integer
          format: int64
        dialogue:
          type: integer
          format: int64
        insight: 
          type: integer
          format: int64
      
    Profile:
      type: object
      required:
        - guid
        - revision
        - node
      properties:
        guid:
          type: string
        handle:
          type: string
        name:
          type: string
        description:
          type: string
        location:
          type: string
        image:
          type: string
          format: base64 encoded data
        revision:
          type: integer
          format: int64
        node:
          type: string
          
    ProfileData:
      type: object
      properties:
        handle:
          type: string
        name:
          type: string
        description:
          type: string
        location:
          type: string
        image:
          type: string
          
    ProfileView:
      type: object
      required:
        - guid
        - imageSet
        - revision
      properties:
        guid:
          type: string
        handle:
          type: string
        name:
          type: string
        description:
          type: string
        location:
          type: string
        imageSet:
          type: boolean
        revision:
          type: integer
          format: int64
          
    App:
      type: object
      required:
        - appId
        - appData
        - attached
      properties:
        appId:
          type: string
        appData:
          $ref: '#/components/schemas/AppData'
        attached:
          type: integer
          format: int32
          
    AppData:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        url:
          type: string
        image:
          type: string
          format: base64 encoded image
          
    Authenticate:
      type: object
      required: 
        - guid
        - token
        - timestamp
      properties:
        token:
          type: string
        timestamp:
          type: integer
          format: int32
          
    Connect:
      type: object
      required:
        - requestorId
        - requestedId
        - timestamp
        - profile
        - token
        - contentRevision
        - conversationRevision
      properties:
        requestorId:
          type: string
        requestedId:
          type: string
        timestamp: 
          type: integer
          format: int32
        profile:
          $ref: '#/components/schemas/Profile'
        token:
          type: string
        contentRevision:
          type: integer
          format: int64
        conversationRevision:
          type: integer
          format: int64
          
    Disconnect:
      type: object
      required:
        - requestorId
        - requestedId
        - timestamp
      properties:
        requestorId:
          type: string
        requestedId:
          type: string
        timestamp: 
          type: integer
          format: int32
          
    DataMessage:
      type: object
      required:
        - message
        - messageType
        - keyType
        - publicKey
        - signature
      properties:
        messageType:
          type: string
          enum: [Connect, Disconnect, Profile, Authenticate]
        message:
          type: string
          format: base64 encoded object
        keyType:
          type: string
          enum: [RSA4096, RSA2048]
        publicKey:
          type: string
          format: base64 encoding of account key
        signature:
          type: string
          format: base64 encoding of message signature
          
          
  securitySchemes:
  
    basicAuth:
      type: http
      scheme: basic
      
    bearerAuth: 
      type: http
      scheme: bearer