swagger.yaml

# this is an example of the Uber API
# as a demonstration of an API spec in YAML
swagger: '2.0'
info:
  title: Passman API
  description: Passman, a simple password manager for owncloud
  version: "1.0.0 draft"
  license:
    name: AGPL
    url: https://github.com/nextcloud/passman/blob/master/LICENSE
# the domain of the service
host: example.com
# array of all schemes that your API supports
schemes:
  - https
# will be prefixed to all paths
basePath: /api/v2

produces:
  - application/json
paths:
  /vaults:
    get:
      summary: Get vaults
      description: |
        The vaults endpoint returns information about the vaults a user has.   
        A vault contains credentials
      tags:
        - Vault
      responses:
        200:
          description: An array of vaults
          schema:
            type: array
            items:
              $ref: '#/definitions/Vault'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    post:
      summary: Create a vault
      tags:
        - Vault        
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              vault_name:
                type: string
      responses:
        200:
          description: The created vault
          schema:
              $ref: '#/definitions/Vault'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'    
            
  /vaults/{vault_id}:
    get:
      summary: Get a vault
      description: |
        Returns a vault, in a vault are the encrypted credentials
      tags:
        - Vault
      
      parameters:
        - name: vault_id 
          in: path
          required: true
          type: integer
          
      responses:
        200:
          description: An array of vaults
          schema:
            type: array
            items:
              $ref: '#/definitions/Credential'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    patch:
      summary: Update a vault
      tags:
        - Vault      
      parameters:
        - name: vault_id
          in: path
          required: true
          type: integer
          
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              vault_name:
                type: string
      responses:
        200:
          description: The updated vault
          schema:
              $ref: '#/definitions/Vault'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'      
  
    delete:
      summary: Delete a vault permanently
      tags:
        - Item      
      parameters:
        - name: vault_id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: OK

        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'    
  
  /credentials:
    post:
      summary: Create a credential
      description: |
        Posting to this endpoint will create an item. No need to set item_id when creating an item.
      tags:
        - Credential        
      parameters:
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/Credential'
      responses:
        200:
          description: The created item
          schema:
              $ref: '#/definitions/Credential'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error' 
  
  /credentials/{credential_id}:
    get: 
      summary: Get an item
      tags:
        - Credential      
      parameters:
        - name: credential_id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: The requested item
          schema:
              $ref: '#/definitions/Credential'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'       
    patch:
      summary: Update an item
      tags:
        - Credential      
      parameters:
        - name: credential_id
          in: path
          required: true
          type: integer
          
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/Credential'
      responses:
        200:
          description: The updated item
          schema:
              $ref: '#/definitions/Credential'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'  
    delete:
      summary: Delete an item permanently
      description: For a 'soft' delete set delete_time
      tags:
        - Credential      
      parameters:
        - name: credential_id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: OK

        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'  
 
 
 
  /credentials/{credential_id}/revisions:
    get:
      summary: Get revisions
      tags:
        - Revision      
      parameters:
        - name: credential_id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: The updated vault
          schema:
              $ref: '#/definitions/CredentialRevision'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'  



  /credentials/{credential_id}/revisions/{revision_id}:
    delete:
      summary: Delete revision
      tags:
        - Revision      
      parameters:
        - name: credential_id
          in: path
          required: true
          type: integer
        - name: revision_id
          in: path
          required: true
          type: integer          
      responses:
        200:
          description: OK

        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'   
  

  /file:
    post:
      summary: Upload and attach a file to an item
      tags:
        - File     
      consumes:
        - multipart/form-data
      parameters:
        - name: file
          in: formData
          description: The uploaded file data
          required: true
          type: file        
      responses:
        200:
          description: The result
          schema:
            type: object
            properties:
              result:
                type: boolean
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'   
  
  /file/{file_id}:
    delete:
      tags:
        - File      
      summary: Delete a file
      parameters:
        - name: file_id
          in: path
          required: true
          type: integer      
      responses:
        200:
          description: OK
    get:
      tags:
        - File      
      summary: Get file contents
      parameters:
        - name: file_id
          in: path
          required: true
          type: integer      
      responses:
        200:
          description: OK    
            
definitions:
  Vault:
    type: object
    properties:
      vault_id:
        type: integer
        format: int64
        description: The id of the vault, generated by uniqid()
      name:
        type: string
        description: Name of the vault
      created:
        type: string
        format: dateTime
        description: Time the vault was created

  Credential:
    type: object
    properties:
      item_id:
        type: integer
        format: int64
        description: generated by uniqid()
      user_id:
        type: string
      vault:
        type: integer
        description: The id of the vault the item belongs to
      label:
        type: string
        description: Name of the item
      description:
        type: string
        description: Description the user has given to the item
      created:
        type: string
        format: dateTime
        description: Time the item was created
      changed:
        type: string
        format: dateTime
        description: Time the item was changed
      tags:
        type: array
        items:
          $ref: '#/definitions/Tag'
      email:
        type: string
        description: Saved e-mail
      username:
        type: string
        description: Saved username
      password: 
        type: string
        description: The stored password, encrypted with sjcl        
      url:
        type: string
        description: Saved url of the item
      favicon:
        type: string
        description: Fav icon from the url
      renew_interval:
        type: integer
        description: x
      expire_time:
        type: string
        format: dateTime
        description: Timestamp when the password expires, set NULL to not expire items
      delete_time:
        type: string
        format: dateTime
        description: If an item is deleted this contains the timestamp, else it's 0

      files:
        type: array
        description: An array containing encrypted files
        items:
          $ref: '#/definitions/File'
      custom_fields:
        type: array
        description: An array of user defined fields
        items:
          $ref: '#/definitions/CustomField'          
      otp:
        type: object
        description: This field holds the One Time Password data
        properties:
          otp_secret:
            type: string
          qr_uri:
            type: string
  
  
  CredentialRevision:
    type: object
    properties:
      revision_id: 
        type: integer
        format: int64
      created: 
        type: string
        format: dateTime
      credential:
          $ref: '#/definitions/Credential'
          
        
  File:
    type: object
    properties:
      file_id:
        type: integer
        format: int64
        description: The file id, generated by uniqid()
      filename: 
        type: string
        description: The uploaded file name
      guid: 
        type: string
        description: The guid of the file
      size:
        type: integer
        description: Size of the file in bytes
      file_data:
        type: string
        description: sjcl encrypted file (only given when downloading a file)
      created:
        type: string
        format: dateTime
        
        
  CustomField:
    type: object
    properties:
      label:
        type: string
        description: Label of the custom field
      value:
        type: string
        description: Value of the custom field
      
  
  Tag:
    type: object
    properties:
      tag_id: 
        type: integer
      name: 
        type: string

  Error:
    type: object
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string