Transferring API Description file from Apiary.io

1 files changed, 415 insertions, 79 deletions

diff --git a/swagger.yaml b/swagger.yaml
index f569ad24..7757426c 100644
--- a/swagger.yaml
+++ b/swagger.yaml
@@ -1,138 +1,474 @@
-swagger: "2.0"
+# this is an example of the Uber API
+# as a demonstration of an API spec in YAML
+swagger: '2.0'
 info:
-  version: 1.0.0
-  title: Passman
-  description: Passman is a simple to use password manager for Nextcloud
-  termsOfService: http://swagger.io/terms/
-  contact:
-    name: Swagger API Team
-    email: foo@example.com
-    url: http://madskristensen.net
+  title: Passman API
+  description: Passman, a simple password manager for owncloud
+  version: "1.0.0 draft"
   license:
-    name: MIT
-    url: http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT
-host: petstore.swagger.io
-basePath: /api
+    name: AGPL
+    url: https://github.com/nextcloud/passman/blob/master/LICENSE
+# the domain of the service
+host: api.uber.com
+# array of all schemes that your API supports
 schemes:
-  - http
-consumes:
-  - application/json
+  - https
+# will be prefixed to all paths
+basePath: /api/v1
+
 produces:
   - application/json
 paths:
   /vaults:
     get:
+      summary: Get vaults
       description: |
-        Returns all the vauls for the current user.
-        A vault contains the users 
-      operationId: findPets
+        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: tags
-          in: query
-          description: tags to filter by
-          required: false
-          type: array
-          collectionFormat: csv
-          items:
-            type: string
-        - name: limit
-          in: query
-          description: maximum number of results to return
-          required: false
+        - 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
-          format: int32
+          
       responses:
         200:
-          description: pet response
+          description: An array of vaults
           schema:
             type: array
             items:
-              $ref: '#/definitions/Pet'
+              $ref: '#/definitions/Credential'
         default:
-          description: unexpected error
+          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:
-      description: Creates a new pet in the store.  Duplicates are allowed
-      operationId: addPet
+      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: pet
+        - name: body
           in: body
-          description: Pet to add to the store
           required: true
           schema:
-            $ref: '#/definitions/NewPet'
+            $ref: '#/definitions/Credential'
       responses:
         200:
-          description: pet response
+          description: The created item
           schema:
-            $ref: '#/definitions/Pet'
+              $ref: '#/definitions/Credential'
         default:
-          description: unexpected error
+          description: Unexpected error
           schema:
-            $ref: '#/definitions/Error'
-  /pets/{id}:
+            $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 a 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 a 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:
-      description: Returns a user based on a single ID, if the user does not have access to the pet
-      operationId: find pet by id
+      summary: Get revisions
+      tags:
+        - Revision      
       parameters:
-        - name: id
+        - name: credential_id
           in: path
-          description: ID of pet to fetch
           required: true
           type: integer
-          format: int64
       responses:
         200:
-          description: pet response
+          description: The updated vault
           schema:
-            $ref: '#/definitions/Pet'
+              $ref: '#/definitions/CredentialRevision'
         default:
-          description: unexpected error
+          description: Unexpected error
           schema:
-            $ref: '#/definitions/Error'
+            $ref: '#/definitions/Error'  
+
+
+
+  /credentials/{credential_id}/revisions/{revision_id}:
     delete:
-      description: deletes a single pet based on the ID supplied
-      operationId: deletePet
+      summary: Delete revision
+      tags:
+        - Revision      
       parameters:
-        - name: id
+        - name: credential_id
           in: path
-          description: ID of pet to delete
           required: true
           type: integer
-          format: int64
+        - name: revision_id
+          in: path
+          required: true
+          type: integer          
       responses:
-        204:
-          description: pet deleted
+        200:
+          description: OK
+
         default:
-          description: unexpected error
+          description: Unexpected error
           schema:
-            $ref: '#/definitions/Error'
+            $ref: '#/definitions/Error'   
+  
+
+  /credentials/{credential_id}/file:
+    post:
+      summary: Upload and attach a file to an item
+      tags:
+        - File     
+      consumes:
+        - multipart/form-data
+      parameters:
+        - name: credential_id
+          in: path
+          required: true
+          type: integer
+        - 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'   
+  
+  /credentials/{credential_id}/file/{file_id}:
+    delete:
+      tags:
+        - File      
+      summary: Delete a file
+      parameters:
+        - name: credential_id
+          in: path
+          required: true
+          type: integer      
+        - name: file_id
+          in: path
+          required: true
+          type: integer      
+      responses:
+        200:
+          description: OK
+    
+            
 definitions:
-  Pet:
-    allOf:
-      - $ref: '#/definitions/NewPet'
-      - required:
-        - id
-        properties:
-          id:
-            type: integer
-            format: int64
-  NewPet:
-    required:
-      - name
+  Vault:
+    type: object
     properties:
+      vault_id:
+        type: integer
+        format: int64
+        description: The id of the vault
       name:
         type: string
-      tag:
+        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
+      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 the item has given
+      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
+      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_code:
+            type: string
+  
+  
+  CredentialRevision:
+    type: object
+    properties:
+      revision_id: 
+        type: integer
+        format: int64
+      created: 
+        type: string
+        format: dateTime
+      item:
+          $ref: '#/definitions/Credential'
+          
+        
+  File:
+    type: object
+    properties:
+      file_id:
+        type: integer
+        format: int64
+        description: The file id
+      filename: 
+        type: string
+        description: The uploaded file name
+      type:
+        type: string
+        description: Detected file type
+      mimetype:
+        type: string
+        description: Mime type of the file
+      size:
+        type: integer
+        description: Size of the file in bytes
+      file_data:
+        type: string
+        description: sjcl encrypted 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:
-    required:
-      - code
-      - message
+    type: object
     properties:
       code:
         type: integer
         format: int32
       message:
+        type: string
+      fields:
         type: string
\ No newline at end of file