From ee8ee5a549b9a1c59c7e83f761e27044d9d5cd33 Mon Sep 17 00:00:00 2001 From: Sander Date: Thu, 8 Sep 2016 19:30:51 +0200 Subject: [PATCH 1/5] Transferring API Description file from Apiary.io --- swagger.yaml | 138 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 swagger.yaml diff --git a/swagger.yaml b/swagger.yaml new file mode 100644 index 00000000..f569ad24 --- /dev/null +++ b/swagger.yaml @@ -0,0 +1,138 @@ +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 + license: + name: MIT + url: http://github.com/gruntjs/grunt/blob/master/LICENSE-MIT +host: petstore.swagger.io +basePath: /api +schemes: + - http +consumes: + - application/json +produces: + - application/json +paths: + /vaults: + get: + description: | + Returns all the vauls for the current user. + A vault contains the users + operationId: findPets + 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 + type: integer + format: int32 + responses: + 200: + description: pet response + schema: + type: array + items: + $ref: '#/definitions/Pet' + default: + description: unexpected error + schema: + $ref: '#/definitions/Error' + post: + description: Creates a new pet in the store. Duplicates are allowed + operationId: addPet + parameters: + - name: pet + in: body + description: Pet to add to the store + required: true + schema: + $ref: '#/definitions/NewPet' + responses: + 200: + description: pet response + schema: + $ref: '#/definitions/Pet' + default: + description: unexpected error + schema: + $ref: '#/definitions/Error' + /pets/{id}: + 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 + parameters: + - name: id + in: path + description: ID of pet to fetch + required: true + type: integer + format: int64 + responses: + 200: + description: pet response + schema: + $ref: '#/definitions/Pet' + default: + description: unexpected error + schema: + $ref: '#/definitions/Error' + delete: + description: deletes a single pet based on the ID supplied + operationId: deletePet + parameters: + - name: id + in: path + description: ID of pet to delete + required: true + type: integer + format: int64 + responses: + 204: + description: pet deleted + default: + description: unexpected error + schema: + $ref: '#/definitions/Error' +definitions: + Pet: + allOf: + - $ref: '#/definitions/NewPet' + - required: + - id + properties: + id: + type: integer + format: int64 + NewPet: + required: + - name + properties: + name: + type: string + tag: + type: string + Error: + required: + - code + - message + properties: + code: + type: integer + format: int32 + message: + type: string \ No newline at end of file From 2517123be2a5572e0d8ce1c8efd176ec14acd75c Mon Sep 17 00:00:00 2001 From: Sander Date: Thu, 8 Sep 2016 22:42:17 +0200 Subject: [PATCH 2/5] Transferring API Description file from Apiary.io --- swagger.yaml | 502 ++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 419 insertions(+), 83 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 - 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 - type: integer - format: int32 + The vaults endpoint returns information about the vaults a user has. + A vault contains credentials + tags: + - Vault responses: 200: - description: pet response + description: An array of vaults schema: type: array items: - $ref: '#/definitions/Pet' + $ref: '#/definitions/Vault' default: - description: unexpected error + description: Unexpected error schema: $ref: '#/definitions/Error' post: - description: Creates a new pet in the store. Duplicates are allowed - operationId: addPet + summary: Create a vault + tags: + - Vault parameters: - - name: pet + - name: body in: body - description: Pet to add to the store required: true schema: - $ref: '#/definitions/NewPet' + type: object + properties: + vault_name: + type: string responses: 200: - description: pet response + description: The created vault schema: - $ref: '#/definitions/Pet' + $ref: '#/definitions/Vault' default: - description: unexpected error + description: Unexpected error schema: - $ref: '#/definitions/Error' - /pets/{id}: + $ref: '#/definitions/Error' + + /vaults/{vault_id}: 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 a vault + description: | + Returns a vault, in a vault are the encrypted credentials + tags: + - Vault + parameters: - - name: id + - name: vault_id in: path - description: ID of pet to fetch required: true type: integer - format: int64 + responses: 200: - description: pet response + description: An array of vaults schema: - $ref: '#/definitions/Pet' + type: array + items: + $ref: '#/definitions/Credential' default: - description: unexpected error + description: Unexpected error schema: $ref: '#/definitions/Error' - delete: - description: deletes a single pet based on the ID supplied - operationId: deletePet + patch: + summary: Update a vault + tags: + - Vault parameters: - - name: id + - name: vault_id in: path - description: ID of pet to delete required: true type: integer - format: int64 - responses: - 204: - description: pet deleted - default: - description: unexpected error + + - name: body + in: body + required: true schema: - $ref: '#/definitions/Error' + 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 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: + 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' + + + /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 From 978c19fe9362c80a96f28acdf5f2bfed7a99d575 Mon Sep 17 00:00:00 2001 From: Sander Date: Thu, 8 Sep 2016 23:48:01 +0200 Subject: [PATCH 3/5] Transferring API Description file --- swagger.yaml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/swagger.yaml b/swagger.yaml index 7757426c..12c230ee 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -374,6 +374,9 @@ definitions: favicon: type: string description: Fav icon from the url + renew_interval: + type: integer + description: x expire_time: type: string format: dateTime From 7e98cbee888c2d0b1809df052f6152bddee98fc1 Mon Sep 17 00:00:00 2001 From: Sander Date: Fri, 9 Sep 2016 12:10:33 +0200 Subject: [PATCH 4/5] Transferring API Description file --- swagger.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/swagger.yaml b/swagger.yaml index 12c230ee..585030bc 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -8,8 +8,8 @@ info: license: name: AGPL url: https://github.com/nextcloud/passman/blob/master/LICENSE -# the domain of the service -host: api.uber.com +# the domain of the servi +host: localhost # array of all schemes that your API supports schemes: - https From dd31b8499eda413cbe0a455d322e898c604b2507 Mon Sep 17 00:00:00 2001 From: Sander Date: Fri, 9 Sep 2016 12:10:43 +0200 Subject: [PATCH 5/5] Transferring API Description file --- swagger.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/swagger.yaml b/swagger.yaml index 585030bc..7eeb6572 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -8,7 +8,7 @@ info: license: name: AGPL url: https://github.com/nextcloud/passman/blob/master/LICENSE -# the domain of the servi +# the domain of the service host: localhost # array of all schemes that your API supports schemes: