mirror of
https://github.com/nextcloud/passman.git
synced 2025-11-04 09:53:29 +08:00
478 lines
No EOL
11 KiB
YAML
478 lines
No EOL
11 KiB
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 |