640 lines
18 KiB
YAML
640 lines
18 KiB
YAML
openapi: 3.0.0
|
|
|
|
info:
|
|
title: Ringfinger API
|
|
version: 1.0.0
|
|
description: The restfull API of the jabber fingerprint keyring.
|
|
|
|
tags:
|
|
- name: User
|
|
description: A user that can login, store fingerprints and share them with other users.
|
|
- name: Fingerprint
|
|
description: The jabber fingerprint owned by a user.
|
|
- name: Sharing
|
|
description: The sharing of all fingerprints of a user with another user.
|
|
|
|
paths:
|
|
'/api/v1/user/{userId}':
|
|
get:
|
|
tags:
|
|
- User
|
|
summary: Returns the user attributes
|
|
parameters:
|
|
- $ref: '#/components/parameters/UserId'
|
|
responses:
|
|
200:
|
|
description: Returns the user data for the given id.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
result:
|
|
type: object
|
|
description: Contains the user data.
|
|
properties:
|
|
userId:
|
|
$ref: '#/components/schemas/UserId'
|
|
usernamme:
|
|
$ref: '#/components/schemas/Username'
|
|
jabberAddress:
|
|
$ref: '#/components/schemas/JabberAddress'
|
|
isAdmin:
|
|
type: boolean
|
|
description: Returns if the user has admin permissions.
|
|
example: true
|
|
fingerprintIds:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
description: A list of all fingerprint ids of the user.
|
|
example: [25, 42, 88]
|
|
default: []
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
put:
|
|
tags:
|
|
- User
|
|
summary: Changes user attributes
|
|
parameters:
|
|
- $ref: '#/components/parameters/UserId'
|
|
requestBody:
|
|
required: true
|
|
description: Contains the json with the user attributes that have to be changed.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
username:
|
|
$ref: '#/components/schemas/Username'
|
|
password:
|
|
$ref: '#/components/schemas/Password'
|
|
email:
|
|
$ref: '#/components/schemas/EmailAddress'
|
|
jabberAddress:
|
|
$ref: '#/components/schemas/JabberAddress'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
delete:
|
|
tags:
|
|
- User
|
|
summary: Deletes a user
|
|
parameters:
|
|
- $ref: '#/components/parameters/UserId'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/user/{userId}/sharings':
|
|
get:
|
|
tags:
|
|
- User
|
|
summary: A list of all sharings with other users.
|
|
responses:
|
|
200:
|
|
description: Returns the success state and a list with all sharings of the user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
sharings:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example:
|
|
- sharingId: 8
|
|
userId: 25
|
|
userSharingId: 42
|
|
- sharingId: 9
|
|
userId: 25
|
|
userSharingId:
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/user/{userId}/fingerprints':
|
|
get:
|
|
tags:
|
|
- User
|
|
summary: A list containing all fingerprints of the user
|
|
responses:
|
|
200:
|
|
description: Returns the success state and a list with all fingerprints of the user.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
fingerprints:
|
|
type: array
|
|
items:
|
|
type: object
|
|
example:
|
|
- fingerprintId: 8
|
|
fingerprint: '5BDF1668E59F2184582591699F55D9158DEF400A48772887A8F61531ED36B2A'
|
|
userId: 25
|
|
- fingerprintId: 42
|
|
fingerprint: '6FF8842B6D17F5C2098A3DD8AB55D9158DEF400A48772887A8F61531ED36B2A'
|
|
userId: 25
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/user/{userId}/email':
|
|
get:
|
|
tags:
|
|
- User
|
|
parameters:
|
|
- $ref: '#/components/parameters/UserId'
|
|
summary: Returns the user's email address
|
|
responses:
|
|
200:
|
|
description: Contains a JSON object with the success state and the email address.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
email:
|
|
$ref: '#/components/schemas/EmailAddress'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
put:
|
|
tags:
|
|
- User
|
|
summary: Changes the user's email address
|
|
parameters:
|
|
- $ref: '#/components/parameters/UserId'
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
email:
|
|
$ref: '#/components/schemas/EmailAddress'
|
|
allOf:
|
|
- required:
|
|
- email
|
|
responses:
|
|
200:
|
|
description: Returns the success state for the change request.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/user/{userId}/password':
|
|
put:
|
|
tags:
|
|
- User
|
|
summary: Changes the password of the user
|
|
parameters:
|
|
- $ref: '#/components/parameters/UserId'
|
|
requestBody:
|
|
description: The password inside a json object.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
password:
|
|
type: string
|
|
description: The new password.
|
|
example: '12345'
|
|
allOf:
|
|
- required:
|
|
- password
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/user/{userId}/admin':
|
|
post:
|
|
tags:
|
|
- User
|
|
summary: Gives the user admin permissions
|
|
parameters:
|
|
- $ref: '#/components/parameters/UserId'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
delete:
|
|
tags:
|
|
- User
|
|
summary: Removes the user's admin permissions
|
|
parameters:
|
|
- $ref: '#/components/parameters/UserId'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/user':
|
|
post:
|
|
tags:
|
|
- User
|
|
summary: Creates a new user
|
|
requestBody:
|
|
required: true
|
|
description: 'The attributes for the user to be created.'
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
username:
|
|
$ref: '#/components/schemas/Username'
|
|
password:
|
|
$ref: '#/components/schemas/Password'
|
|
email:
|
|
$ref: '#/components/schemas/EmailAddress'
|
|
jabberAddress:
|
|
$ref: '#/components/schemas/JabberAddress'
|
|
allOf:
|
|
- required:
|
|
- username
|
|
- password
|
|
- email
|
|
- jabberAddress
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/user/session':
|
|
post:
|
|
tags:
|
|
- User
|
|
summary: Creates a user session (login)
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
username:
|
|
$ref: '#/components/schemas/Username'
|
|
password:
|
|
$ref: '#/components/schemas/Password'
|
|
allOf:
|
|
- required:
|
|
- username
|
|
- password
|
|
responses:
|
|
200:
|
|
description: Returns the success state and the user id for the created session.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
userId:
|
|
$ref: '#/components/schemas/UserId'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
delete:
|
|
tags:
|
|
- User
|
|
summary: Deletes a user session (logout)
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/fingerprint/{fingerprintId}/qr':
|
|
get:
|
|
tags:
|
|
- Fingerprint
|
|
summary: Returns the fingerprint's QR code
|
|
parameters:
|
|
- $ref: '#/components/parameters/FingerprintId'
|
|
responses:
|
|
200:
|
|
description: The QR code as SVG image
|
|
content:
|
|
application/svg+xml:
|
|
schema:
|
|
type: string
|
|
description: The xml of the SVG image.
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/fingerprint/{fingerprintId}':
|
|
get:
|
|
tags:
|
|
- Fingerprint
|
|
summary: Returns the attributes of the fingerprint
|
|
parameters:
|
|
- $ref: '#/components/parameters/FingerprintId'
|
|
responses:
|
|
200:
|
|
description: Returns the fingerprint for the given fingerprint id.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FingerprintData'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
put:
|
|
tags:
|
|
- Fingerprint
|
|
summary: Changes the fingerprint
|
|
parameters:
|
|
- $ref: '#/components/parameters/FingerprintId'
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
fingerprint:
|
|
$ref: '#/components/schemas/Fingerprint'
|
|
required:
|
|
- fingerprint
|
|
responses:
|
|
200:
|
|
description: Returns the success state.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
description: 'Returns the success state of the fingerprint change.'
|
|
example: true
|
|
message:
|
|
type: string
|
|
description: 'Returns if no changes have been found inside the request body.'
|
|
example: 'Fingerprint did not differ from the stored. Nothing changed.'
|
|
required:
|
|
- success
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
delete:
|
|
tags:
|
|
- Fingerprint
|
|
summary: Removes the fingerprint
|
|
parameters:
|
|
- $ref: '#/components/parameters/FingerprintId'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/fingerprint':
|
|
post:
|
|
tags:
|
|
- Fingerprint
|
|
summary: Creates a new fingerprint
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: The parameters for the new fingerprint to be created.
|
|
properties:
|
|
fingerprint:
|
|
$ref: '#/components/schemas/Fingerprint'
|
|
userId:
|
|
$ref: '#/components/schemas/UserId'
|
|
required:
|
|
- fingerprint
|
|
- userId
|
|
|
|
responses:
|
|
200:
|
|
description: Returns the confirmation and the id for the newly created fingerprint.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
description: Returns the success status.
|
|
example: true
|
|
fingerprintId:
|
|
type: integer
|
|
description: The id for the newly created fingerprint.
|
|
example: 42
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/sharing/{sharingId}':
|
|
get:
|
|
tags:
|
|
- Sharing
|
|
summary: Returns the sharing attributes
|
|
parameters:
|
|
- $ref: '#/components/parameters/SharingId'
|
|
responses:
|
|
200:
|
|
description: The JSON result for the sharing.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
result:
|
|
type: object
|
|
properties:
|
|
sharingId:
|
|
$ref: '#/components/schemas/SharingId'
|
|
userId:
|
|
type: integer
|
|
description: The id of the user that shares his fingerprints.
|
|
example: 42
|
|
userSharedId:
|
|
$ref: '#/components/schemas/SharingUserId'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
delete:
|
|
tags:
|
|
- Sharing
|
|
summary: Removes the specified sharing
|
|
parameters:
|
|
- $ref: '#/components/parameters/SharingId'
|
|
responses:
|
|
200:
|
|
$ref: '#/components/responses/Success'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
'/api/v1/sharing':
|
|
post:
|
|
tags:
|
|
- Sharing
|
|
summary: Creates a new sharing
|
|
requestBody:
|
|
description: Contains the attributes for the sharing to be created.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
userId:
|
|
type: integer
|
|
description: The id of the user that shares his fingerprints.
|
|
example: 42
|
|
userSharedId:
|
|
$ref: '#/components/schemas/SharingUserId'
|
|
allOf:
|
|
- required:
|
|
- userId
|
|
- userSharedId
|
|
|
|
responses:
|
|
200:
|
|
description: Returns the success flag and the id for the newly created sharing.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
sharingId:
|
|
$ref: '#/components/schemas/SharingId'
|
|
default:
|
|
$ref: '#/components/responses/Error'
|
|
|
|
components:
|
|
parameters:
|
|
FingerprintId:
|
|
name: fingerprintId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/FingerprintId'
|
|
|
|
SharingId:
|
|
name: sharingId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/SharingId'
|
|
|
|
UserId:
|
|
name: userId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
$ref: '#/components/schemas/UserId'
|
|
|
|
responses:
|
|
Success:
|
|
description: Returns that the request could be handled successfully.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
success:
|
|
$ref: '#/components/schemas/Success'
|
|
|
|
Error:
|
|
description: Returns a JSON object that describes the error.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
schemas:
|
|
Error:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
description: Returns that the request couldn't be handled.
|
|
example: false
|
|
message:
|
|
type: string
|
|
description: Description of the error that occured.
|
|
example: Something extremely terrible happened!
|
|
|
|
Success:
|
|
type: boolean
|
|
description: Returns if the request could be handled.
|
|
example: true
|
|
|
|
UserId:
|
|
type: integer
|
|
description: The id of the user in question.
|
|
example: 42
|
|
|
|
Username:
|
|
type: string
|
|
description: The login name for the given user.
|
|
example: Kevin42
|
|
|
|
Password:
|
|
type: string
|
|
description: The password for the user login.
|
|
example: '12345'
|
|
|
|
JabberAddress:
|
|
type: string
|
|
description: The address of the jabber account.
|
|
example: donalt@jabber.de
|
|
|
|
EmailAddress:
|
|
type: string
|
|
description: The registered email address for the user.
|
|
example: kevin42@gmail.com
|
|
|
|
FingerprintId:
|
|
type: integer
|
|
description: The id that identifies the fingerprint.
|
|
example: 42
|
|
readOnly: true
|
|
|
|
Fingerprint:
|
|
type: string
|
|
description: The jabber fingerprint
|
|
example: '5BDF1668E59F2184582591699F55D9158DEF400A48772887A8F61531ED36B2A'
|
|
|
|
FingerprintData:
|
|
type: object
|
|
properties:
|
|
fingerprintId:
|
|
$ref: '#/components/schemas/FingerprintId'
|
|
fingerprint:
|
|
$ref: '#/components/schemas/Fingerprint'
|
|
userId:
|
|
type: integer
|
|
description: The id of the user that owns this fingerprint.
|
|
example: 25
|
|
|
|
SharingId:
|
|
type: integer
|
|
description: The id for the sharing.
|
|
example: 42
|
|
readOnly: true
|
|
|
|
SharingUserId:
|
|
type: integer
|
|
description: The id of the user who is allowed to display the fingerprints.
|
|
example: 25 |