cc-backend/api/swagger.yaml

1251 lines
33 KiB
YAML
Raw Normal View History

basePath: /api
definitions:
2023-08-21 12:12:28 +02:00
api.ApiReturnedUser:
properties:
email:
type: string
name:
type: string
projects:
items:
type: string
type: array
roles:
items:
type: string
type: array
username:
type: string
type: object
api.ApiTag:
properties:
name:
description: Tag Name
example: Testjob
type: string
type:
description: Tag Type
example: Debug
type: string
type: object
api.DeleteJobApiRequest:
properties:
cluster:
description: Cluster of job
example: fritz
type: string
jobId:
description: Cluster Job ID of job
example: 123000
type: integer
startTime:
description: Start Time of job as epoch
example: 1649723812
type: integer
required:
- jobId
type: object
api.DeleteJobApiResponse:
properties:
msg:
type: string
type: object
api.ErrorResponse:
properties:
error:
description: Error Message
type: string
status:
description: Statustext of Errorcode
type: string
type: object
api.GetJobApiResponse:
properties:
data:
items:
$ref: '#/definitions/api.JobMetricWithName'
type: array
meta:
$ref: '#/definitions/schema.Job'
type: object
api.GetJobsApiResponse:
properties:
items:
description: Number of jobs returned
type: integer
jobs:
description: Array of jobs
items:
$ref: '#/definitions/schema.JobMeta'
type: array
page:
description: Page id returned
type: integer
type: object
api.JobMetricWithName:
properties:
metric:
$ref: '#/definitions/schema.JobMetric'
name:
type: string
scope:
$ref: '#/definitions/schema.MetricScope'
type: object
api.StartJobApiResponse:
properties:
id:
description: Database ID of new job
type: integer
type: object
api.StopJobApiRequest:
properties:
cluster:
description: Cluster of job
example: fritz
type: string
jobId:
description: Cluster Job ID of job
example: 123000
type: integer
jobState:
allOf:
- $ref: '#/definitions/schema.JobState'
description: Final job state
example: completed
startTime:
description: Start Time of job as epoch
example: 1649723812
type: integer
stopTime:
description: Stop Time of job as epoch
example: 1649763839
type: integer
required:
- jobState
- stopTime
type: object
schema.Job:
2022-09-21 14:12:24 +02:00
description: Information of a HPC job.
properties:
arrayJobId:
description: The unique identifier of an array job
example: 123000
type: integer
cluster:
description: The unique identifier of a cluster
example: fritz
type: string
2023-06-14 14:33:36 +02:00
concurrentJobs:
$ref: '#/definitions/schema.JobLinkResultList'
duration:
description: Duration of job in seconds (Min > 0)
example: 43200
minimum: 1
type: integer
exclusive:
2022-09-21 14:12:24 +02:00
description: 'Specifies how nodes are shared: 0 - Shared among multiple jobs
of multiple users, 1 - Job exclusive (Default), 2 - Shared among multiple
jobs of same user'
example: 1
maximum: 2
minimum: 0
type: integer
id:
description: The unique identifier of a job in the database
type: integer
jobId:
description: The unique identifier of a job
example: 123000
type: integer
jobState:
allOf:
- $ref: '#/definitions/schema.JobState'
description: Final state of job
2023-06-14 14:33:36 +02:00
enum:
- completed
- failed
- cancelled
- stopped
- timeout
- out_of_memory
example: completed
metaData:
additionalProperties:
type: string
description: Additional information about the job
type: object
monitoringStatus:
2022-09-21 14:12:24 +02:00
description: 'State of monitoring system during job run: 0 - Disabled, 1 -
Running or Archiving (Default), 2 - Archiving Failed, 3 - Archiving Successfull'
example: 1
2022-09-21 14:12:24 +02:00
maximum: 3
minimum: 0
type: integer
numAcc:
description: Number of accelerators used (Min > 0)
example: 2
minimum: 1
type: integer
numHwthreads:
2023-06-14 14:33:36 +02:00
description: NumCores int32 `json:"numCores" db:"num_cores"
example:"20" minimum:"1"` //
Number of HWThreads used (Min > 0)
example: 20
minimum: 1
type: integer
numNodes:
description: Number of nodes used (Min > 0)
example: 2
minimum: 1
type: integer
partition:
description: The Slurm partition to which the job was submitted
example: main
type: string
project:
description: The unique identifier of a project
example: abcd200
type: string
resources:
description: Resources used by job
items:
$ref: '#/definitions/schema.Resource'
type: array
smt:
description: SMT threads used by job
example: 4
type: integer
startTime:
description: Start time as 'time.Time' data type
type: string
subCluster:
description: The unique identifier of a sub cluster
example: main
type: string
tags:
description: List of tags
items:
$ref: '#/definitions/schema.Tag'
type: array
user:
description: The unique identifier of a user
example: abcd100h
type: string
walltime:
description: Requested walltime of job in seconds (Min > 0)
example: 86400
minimum: 1
type: integer
type: object
2023-06-14 14:33:36 +02:00
schema.JobLink:
properties:
id:
type: integer
jobId:
type: integer
type: object
schema.JobLinkResultList:
properties:
count:
type: integer
items:
items:
$ref: '#/definitions/schema.JobLink'
type: array
type: object
schema.JobMeta:
description: Meta data information of a HPC job.
properties:
arrayJobId:
description: The unique identifier of an array job
example: 123000
type: integer
cluster:
description: The unique identifier of a cluster
example: fritz
type: string
2023-06-14 14:33:36 +02:00
concurrentJobs:
$ref: '#/definitions/schema.JobLinkResultList'
duration:
description: Duration of job in seconds (Min > 0)
example: 43200
minimum: 1
type: integer
exclusive:
2022-09-21 14:12:24 +02:00
description: 'Specifies how nodes are shared: 0 - Shared among multiple jobs
of multiple users, 1 - Job exclusive (Default), 2 - Shared among multiple
jobs of same user'
example: 1
maximum: 2
minimum: 0
type: integer
id:
description: The unique identifier of a job in the database
type: integer
jobId:
description: The unique identifier of a job
example: 123000
type: integer
jobState:
allOf:
- $ref: '#/definitions/schema.JobState'
description: Final state of job
2023-06-14 14:33:36 +02:00
enum:
- completed
- failed
- cancelled
- stopped
- timeout
- out_of_memory
example: completed
metaData:
additionalProperties:
type: string
description: Additional information about the job
type: object
monitoringStatus:
2022-09-21 14:12:24 +02:00
description: 'State of monitoring system during job run: 0 - Disabled, 1 -
Running or Archiving (Default), 2 - Archiving Failed, 3 - Archiving Successfull'
example: 1
2022-09-21 14:12:24 +02:00
maximum: 3
minimum: 0
type: integer
numAcc:
description: Number of accelerators used (Min > 0)
example: 2
minimum: 1
type: integer
numHwthreads:
2023-06-14 14:33:36 +02:00
description: NumCores int32 `json:"numCores" db:"num_cores"
example:"20" minimum:"1"` //
Number of HWThreads used (Min > 0)
example: 20
minimum: 1
type: integer
numNodes:
description: Number of nodes used (Min > 0)
example: 2
minimum: 1
type: integer
partition:
description: The Slurm partition to which the job was submitted
example: main
type: string
project:
description: The unique identifier of a project
example: abcd200
type: string
resources:
description: Resources used by job
items:
$ref: '#/definitions/schema.Resource'
type: array
smt:
description: SMT threads used by job
example: 4
type: integer
startTime:
description: Start epoch time stamp in seconds (Min > 0)
example: 1649723812
minimum: 1
type: integer
statistics:
additionalProperties:
$ref: '#/definitions/schema.JobStatistics'
description: Metric statistics of job
type: object
subCluster:
description: The unique identifier of a sub cluster
example: main
type: string
tags:
description: List of tags
items:
$ref: '#/definitions/schema.Tag'
type: array
user:
description: The unique identifier of a user
example: abcd100h
type: string
walltime:
description: Requested walltime of job in seconds (Min > 0)
example: 86400
minimum: 1
type: integer
type: object
schema.JobMetric:
properties:
series:
items:
$ref: '#/definitions/schema.Series'
type: array
statisticsSeries:
$ref: '#/definitions/schema.StatsSeries'
timestep:
type: integer
unit:
$ref: '#/definitions/schema.Unit'
type: object
schema.JobState:
enum:
- running
- completed
- failed
- cancelled
- stopped
- timeout
- preempted
- out_of_memory
type: string
x-enum-varnames:
- JobStateRunning
- JobStateCompleted
- JobStateFailed
- JobStateCancelled
- JobStateStopped
- JobStateTimeout
- JobStatePreempted
- JobStateOutOfMemory
schema.JobStatistics:
description: Specification for job metric statistics.
properties:
avg:
description: Job metric average
example: 2500
minimum: 0
type: number
max:
description: Job metric maximum
example: 3000
minimum: 0
type: number
min:
description: Job metric minimum
example: 2000
minimum: 0
type: number
unit:
2023-06-14 14:33:36 +02:00
$ref: '#/definitions/schema.Unit'
type: object
schema.MetricScope:
enum:
- invalid_scope
- node
- socket
- memoryDomain
- core
- hwthread
- accelerator
type: string
x-enum-varnames:
- MetricScopeInvalid
- MetricScopeNode
- MetricScopeSocket
- MetricScopeMemoryDomain
- MetricScopeCore
- MetricScopeHWThread
- MetricScopeAccelerator
schema.MetricStatistics:
properties:
avg:
type: number
max:
type: number
min:
type: number
type: object
schema.Resource:
description: A resource used by a job
properties:
accelerators:
description: List of of accelerator device ids
items:
type: string
type: array
configuration:
description: The configuration options of the node
type: string
hostname:
description: Name of the host (= node)
type: string
hwthreads:
description: List of OS processor ids
items:
type: integer
type: array
type: object
schema.Series:
properties:
data:
items:
type: number
type: array
hostname:
type: string
id:
type: string
statistics:
$ref: '#/definitions/schema.MetricStatistics'
type: object
schema.StatsSeries:
properties:
max:
items:
type: number
type: array
mean:
items:
type: number
type: array
min:
items:
type: number
type: array
percentiles:
additionalProperties:
items:
type: number
type: array
type: object
type: object
schema.Tag:
2022-11-30 12:40:07 +01:00
description: Defines a tag using name and type.
properties:
id:
description: The unique DB identifier of a tag
type: integer
name:
description: Tag Name
example: Testjob
type: string
type:
description: Tag Type
example: Debug
type: string
type: object
2023-06-14 14:33:36 +02:00
schema.Unit:
properties:
base:
type: string
prefix:
type: string
type: object
host: localhost:8080
info:
contact:
email: support@clustercockpit.org
name: ClusterCockpit Project
url: https://github.com/ClusterCockpit
description: API for batch job control.
license:
name: MIT License
url: https://opensource.org/licenses/MIT
title: ClusterCockpit REST API
version: 1.0.0
paths:
/jobs/:
get:
2022-09-22 13:32:40 +02:00
description: |-
Get a list of all jobs. Filters can be applied using query parameters.
Number of results can be limited by page. Results are sorted by descending startTime.
parameters:
- description: Job State
enum:
- running
- completed
- failed
- cancelled
- stopped
- timeout
in: query
name: state
type: string
- description: Job Cluster
in: query
name: cluster
type: string
- description: 'Syntax: ''$from-$to'', as unix epoch timestamps in seconds'
in: query
name: start-time
type: string
- description: 'Items per page (Default: 25)'
in: query
2022-09-22 13:32:40 +02:00
name: items-per-page
type: integer
- description: 'Page Number (Default: 1)'
in: query
2022-09-22 13:32:40 +02:00
name: page
type: integer
2022-09-22 13:32:40 +02:00
- description: Include metadata (e.g. jobScript) in response
in: query
name: with-metadata
type: boolean
produces:
- application/json
responses:
"200":
description: Job array and page info
schema:
$ref: '#/definitions/api.GetJobsApiResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
2022-09-21 17:13:55 +02:00
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Lists all jobs
tags:
2023-09-07 15:14:09 +02:00
- Job query
2023-06-14 14:33:36 +02:00
/jobs/{id}:
post:
2023-06-14 14:33:36 +02:00
consumes:
- application/json
description: |-
Job to get is specified by database ID
Returns full job resource information according to 'JobMeta' scheme and all metrics according to 'JobData'.
parameters:
- description: Database ID of Job
in: path
name: id
required: true
type: integer
- description: Array of metric names
in: body
name: request
required: true
schema:
items:
type: string
type: array
produces:
- application/json
responses:
"200":
description: Job resource
schema:
$ref: '#/definitions/api.GetJobApiResponse'
2023-06-14 14:33:36 +02:00
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.ErrorResponse'
"404":
description: Resource not found
schema:
$ref: '#/definitions/api.ErrorResponse'
"422":
description: 'Unprocessable Entity: finding job failed: sql: no rows in
result set'
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Get complete job meta and metric data
tags:
2023-09-07 15:14:09 +02:00
- Job query
/jobs/delete_job/:
delete:
consumes:
- application/json
description: Job to delete is specified by request body. All fields are required
in this case.
parameters:
- description: All fields required
in: body
name: request
required: true
schema:
$ref: '#/definitions/api.DeleteJobApiRequest'
produces:
- application/json
responses:
"200":
description: Success message
schema:
$ref: '#/definitions/api.DeleteJobApiResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.ErrorResponse'
"404":
description: Resource not found
schema:
$ref: '#/definitions/api.ErrorResponse'
"422":
description: 'Unprocessable Entity: finding job failed: sql: no rows in
result set'
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Remove a job from the sql database
tags:
2023-09-07 15:14:09 +02:00
- Job remove
/jobs/delete_job/{id}:
delete:
description: Job to remove is specified by database ID. This will not remove
the job from the job archive.
parameters:
- description: Database ID of Job
in: path
name: id
required: true
type: integer
produces:
- application/json
responses:
"200":
description: Success message
schema:
$ref: '#/definitions/api.DeleteJobApiResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.ErrorResponse'
"404":
description: Resource not found
schema:
$ref: '#/definitions/api.ErrorResponse'
"422":
description: 'Unprocessable Entity: finding job failed: sql: no rows in
result set'
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Remove a job from the sql database
tags:
2023-09-07 15:14:09 +02:00
- Job remove
/jobs/delete_job_before/{ts}:
delete:
2022-11-30 12:40:07 +01:00
description: Remove all jobs with start time before timestamp. The jobs will
not be removed from the job archive.
parameters:
- description: Unix epoch timestamp
in: path
name: ts
required: true
type: integer
produces:
- application/json
responses:
"200":
description: Success message
schema:
$ref: '#/definitions/api.DeleteJobApiResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.ErrorResponse'
"404":
description: Resource not found
schema:
$ref: '#/definitions/api.ErrorResponse'
"422":
description: 'Unprocessable Entity: finding job failed: sql: no rows in
result set'
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Remove a job from the sql database
tags:
2023-09-07 15:14:09 +02:00
- Job remove
/jobs/start_job/:
post:
consumes:
- application/json
description: |-
Job specified in request body will be saved to database as "running" with new DB ID.
Job specifications follow the 'JobMeta' scheme, API will fail to execute if requirements are not met.
parameters:
- description: Job to add
in: body
name: request
required: true
schema:
$ref: '#/definitions/schema.JobMeta'
produces:
- application/json
responses:
"201":
description: Job added successfully
schema:
$ref: '#/definitions/api.StartJobApiResponse'
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
2022-09-21 17:13:55 +02:00
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.ErrorResponse'
"422":
description: 'Unprocessable Entity: The combination of jobId, clusterId
and startTime does already exist'
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Adds a new job as "running"
tags:
2023-09-07 15:14:09 +02:00
- Job add and modify
/jobs/stop_job/:
post:
description: |-
Job to stop is specified by request body. All fields are required in this case.
Returns full job resource information according to 'JobMeta' scheme.
parameters:
- description: All fields required
in: body
name: request
required: true
schema:
$ref: '#/definitions/api.StopJobApiRequest'
produces:
- application/json
responses:
"200":
description: Success message
schema:
2022-09-16 11:21:27 +02:00
$ref: '#/definitions/schema.JobMeta'
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
2022-09-21 17:13:55 +02:00
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.ErrorResponse'
"404":
description: Resource not found
schema:
$ref: '#/definitions/api.ErrorResponse'
"422":
description: 'Unprocessable Entity: finding job failed: sql: no rows in
result set'
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Marks job as completed and triggers archiving
tags:
2023-09-07 15:14:09 +02:00
- Job add and modify
/jobs/stop_job/{id}:
post:
consumes:
- application/json
description: |-
Job to stop is specified by database ID. Only stopTime and final state are required in request body.
Returns full job resource information according to 'JobMeta' scheme.
parameters:
- description: Database ID of Job
in: path
name: id
required: true
type: integer
- description: stopTime and final state in request body
in: body
name: request
required: true
schema:
$ref: '#/definitions/api.StopJobApiRequest'
produces:
- application/json
responses:
"200":
description: Job resource
schema:
$ref: '#/definitions/schema.JobMeta'
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
2022-09-21 17:13:55 +02:00
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"403":
description: Forbidden
schema:
$ref: '#/definitions/api.ErrorResponse'
"404":
description: Resource not found
schema:
$ref: '#/definitions/api.ErrorResponse'
"422":
description: 'Unprocessable Entity: finding job failed: sql: no rows in
result set'
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Marks job as completed and triggers archiving
tags:
2023-09-07 15:14:09 +02:00
- Job add and modify
/jobs/tag_job/{id}:
post:
consumes:
- application/json
description: |-
Adds tag(s) to a job specified by DB ID. Name and Type of Tag(s) can be chosen freely.
If tagged job is already finished: Tag will be written directly to respective archive files.
parameters:
- description: Job Database ID
in: path
name: id
required: true
type: integer
- description: Array of tag-objects to add
in: body
name: request
required: true
schema:
items:
$ref: '#/definitions/api.ApiTag'
type: array
produces:
- application/json
responses:
"200":
2022-09-22 13:32:40 +02:00
description: Updated job resource
schema:
$ref: '#/definitions/schema.Job'
"400":
description: Bad Request
schema:
$ref: '#/definitions/api.ErrorResponse'
2022-09-21 17:13:55 +02:00
"401":
description: Unauthorized
schema:
$ref: '#/definitions/api.ErrorResponse'
"404":
description: Job or tag does not exist
schema:
$ref: '#/definitions/api.ErrorResponse'
"500":
description: Internal Server Error
schema:
$ref: '#/definitions/api.ErrorResponse'
security:
- ApiKeyAuth: []
summary: Adds one or more tags to a job
tags:
2023-09-07 15:14:09 +02:00
- Job add and modify
/user/{id}:
post:
consumes:
- multipart/form-data
description: |-
Modifies user defined by username (id) in one of four possible ways.
If more than one formValue is set then only the highest priority field is used.
2023-09-07 14:33:22 +02:00
Only accessible from IPs registered with apiAllowedIPs configuration option.
parameters:
- description: Database ID of User
in: path
name: id
required: true
type: string
2023-08-21 12:12:28 +02:00
- description: 'Priority 1: Role to add'
enum:
- admin
- support
- manager
- user
- api
in: formData
name: add-role
type: string
2023-08-21 12:12:28 +02:00
- description: 'Priority 2: Role to remove'
enum:
- admin
- support
- manager
- user
- api
in: formData
name: remove-role
type: string
- description: 'Priority 3: Project to add'
in: formData
name: add-project
type: string
- description: 'Priority 4: Project to remove'
in: formData
name: remove-project
type: string
produces:
- text/plain
responses:
"200":
2023-08-21 12:12:28 +02:00
description: Success Response Message
schema:
type: string
"400":
description: Bad Request
schema:
2023-08-21 12:12:28 +02:00
type: string
"401":
description: Unauthorized
schema:
2023-08-21 12:12:28 +02:00
type: string
"403":
description: Forbidden
schema:
2023-08-21 12:12:28 +02:00
type: string
"422":
description: 'Unprocessable Entity: The user could not be updated'
schema:
2023-08-21 12:12:28 +02:00
type: string
"500":
description: Internal Server Error
schema:
2023-08-21 12:12:28 +02:00
type: string
security:
- ApiKeyAuth: []
summary: Updates an existing user
tags:
2023-09-07 15:14:09 +02:00
- User
/users/:
delete:
consumes:
- multipart/form-data
2023-09-07 14:33:22 +02:00
description: |-
User defined by username in form data will be deleted from database.
Only accessible from IPs registered with apiAllowedIPs configuration option.
parameters:
- description: User ID to delete
in: formData
name: username
required: true
type: string
2023-08-21 12:12:28 +02:00
produces:
- text/plain
responses:
"200":
description: User deleted successfully
"400":
description: Bad Request
schema:
2023-08-21 12:12:28 +02:00
type: string
"401":
description: Unauthorized
schema:
2023-08-21 12:12:28 +02:00
type: string
"403":
description: Forbidden
schema:
2023-08-21 12:12:28 +02:00
type: string
"422":
description: 'Unprocessable Entity: deleting user failed'
schema:
2023-08-21 12:12:28 +02:00
type: string
"500":
description: Internal Server Error
schema:
2023-08-21 12:12:28 +02:00
type: string
security:
- ApiKeyAuth: []
summary: Deletes a user
tags:
2023-09-07 15:14:09 +02:00
- User
get:
description: |-
Returns a JSON-encoded list of users.
Required query-parameter defines if all users or only users with additional special roles are returned.
2023-09-07 14:33:22 +02:00
Only accessible from IPs registered with apiAllowedIPs configuration option.
parameters:
- description: If returned list should contain all users or only users with
additional special roles
in: query
name: not-just-user
required: true
type: boolean
produces:
- application/json
responses:
"200":
2023-08-21 12:12:28 +02:00
description: List of users returned successfully
schema:
2023-08-21 12:12:28 +02:00
items:
$ref: '#/definitions/api.ApiReturnedUser'
type: array
"400":
description: Bad Request
schema:
2023-08-21 12:12:28 +02:00
type: string
"401":
description: Unauthorized
schema:
2023-08-21 12:12:28 +02:00
type: string
"403":
description: Forbidden
schema:
2023-08-21 12:12:28 +02:00
type: string
"500":
description: Internal Server Error
schema:
2023-08-21 12:12:28 +02:00
type: string
security:
- ApiKeyAuth: []
summary: Returns a list of users
tags:
2023-09-07 15:14:09 +02:00
- User
post:
consumes:
- multipart/form-data
2023-09-07 14:33:22 +02:00
description: |-
User specified in form data will be saved to database.
Only accessible from IPs registered with apiAllowedIPs configuration option.
parameters:
- description: Unique user ID
in: formData
name: username
required: true
type: string
- description: User password
in: formData
name: password
required: true
type: string
2023-08-21 12:12:28 +02:00
- description: User role
enum:
- admin
- support
- manager
- user
- api
in: formData
name: role
required: true
type: string
- description: Managed project, required for new manager role user
in: formData
name: project
type: string
- description: Users name
in: formData
name: name
type: string
- description: Users email
in: formData
name: email
type: string
produces:
- text/plain
responses:
"200":
2023-08-21 12:12:28 +02:00
description: Success Response
schema:
type: string
"400":
description: Bad Request
schema:
2023-08-21 12:12:28 +02:00
type: string
"401":
description: Unauthorized
schema:
2023-08-21 12:12:28 +02:00
type: string
"403":
description: Forbidden
schema:
2023-08-21 12:12:28 +02:00
type: string
"422":
description: 'Unprocessable Entity: creating user failed'
schema:
2023-08-21 12:12:28 +02:00
type: string
"500":
description: Internal Server Error
schema:
2023-08-21 12:12:28 +02:00
type: string
security:
- ApiKeyAuth: []
summary: Adds a new user
tags:
2023-09-07 15:14:09 +02:00
- User
securityDefinitions:
ApiKeyAuth:
in: header
name: X-Auth-Token
type: apiKey
swagger: "2.0"