passman/swagger.yaml

478 lines
11 KiB
YAML
Raw Normal View History

# 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
2016-09-09 18:10:43 +08:00
# 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 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'
/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
2016-09-10 23:08:00 +08:00
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
2016-09-10 23:08:00 +08:00
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 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
2016-09-09 05:48:01 +08:00
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
2016-09-10 23:08:00 +08:00
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
2016-09-10 23:08:00 +08:00
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