mirror of
https://github.com/goharbor/harbor.git
synced 2024-12-20 23:57:42 +01:00
1729 lines
52 KiB
YAML
1729 lines
52 KiB
YAML
# this is an example of the Uber API
|
|
# as a demonstration of an API spec in YAML
|
|
swagger: '2.0'
|
|
info:
|
|
title: Harbor API
|
|
description: These APIs provide services for manipulating Harbor project.
|
|
version: "0.3.0"
|
|
# the domain of the service
|
|
host: localhost
|
|
# array of all schemes that your API supports
|
|
schemes:
|
|
- http
|
|
basePath: /api
|
|
produces:
|
|
- application/json
|
|
- text/plain
|
|
consumes:
|
|
- text/plain
|
|
- application/json
|
|
paths:
|
|
/search:
|
|
get:
|
|
summary: Search for projects and repositories
|
|
description: |
|
|
The Search endpoint returns information about the projects and repositories
|
|
offered at public status or related to the current logged in user. The
|
|
response includes the project and repository list in a proper
|
|
display order.
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
description: Search parameter for project and repository name.
|
|
required: true
|
|
type: string
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: An array of search results
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Search'
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/projects:
|
|
get:
|
|
summary: Return projects created by Harbor
|
|
description: |
|
|
This endpoint returns all projects created by Harbor, and can be filtered by project name.
|
|
parameters:
|
|
- name: project_name
|
|
in: query
|
|
description: Project name for filtering results.
|
|
required: false
|
|
type: string
|
|
- name: is_public
|
|
in: query
|
|
description: Public sign for filtering projects.
|
|
required: false
|
|
type: integer
|
|
format: int32
|
|
- name: page
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The page nubmer, default is 1.
|
|
- name: page_size
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The size of per page, default is 10, maximum is 100.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Return all matched projects.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Project'
|
|
headers:
|
|
X-Total-Count:
|
|
description: The total count of projects
|
|
type: integer
|
|
Link:
|
|
description: Link refers to the previous page and next page
|
|
type: string
|
|
401:
|
|
description: User need to log in first.
|
|
500:
|
|
description: Internal errors.
|
|
head:
|
|
summary: Check if the project name user provided already exists.
|
|
description: |
|
|
This endpoint is used to check if the project name user provided already exist.
|
|
parameters:
|
|
- name: project_name
|
|
in: query
|
|
description: Project name for checking exists.
|
|
required: true
|
|
type: string
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Project name exists.
|
|
401:
|
|
description: User need to log in first.
|
|
404:
|
|
description: Project name does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
post:
|
|
summary: Create a new project.
|
|
description: |
|
|
This endpoint is for user to create a new project.
|
|
parameters:
|
|
- name: project
|
|
in: body
|
|
description: New created project.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/ProjectReq'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
201:
|
|
description: Project created successfully.
|
|
400:
|
|
description: Unsatisfied with constraints of the project creation.
|
|
401:
|
|
description: User need to log in first.
|
|
409:
|
|
description: Project name already exists.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/projects/{project_id}:
|
|
get:
|
|
summary: Return specific project detail infomation
|
|
description: |
|
|
This endpoint returns specific project information by project ID.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
description: Project ID for filtering results.
|
|
required: true
|
|
type: integer
|
|
format: int64
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Return matched project information.
|
|
schema:
|
|
$ref: '#/definitions/Project'
|
|
401:
|
|
description: User need to log in first.
|
|
500:
|
|
description: Internal errors.
|
|
delete:
|
|
summary: Delete project by projectID
|
|
description: |
|
|
This endpoint is aimed to delete project by project ID.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
description: Project ID of project which will be deleted.
|
|
required: true
|
|
type: integer
|
|
format: int64
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Project is deleted successfully.
|
|
400:
|
|
description: Invalid project id.
|
|
403:
|
|
description: User need to log in first.
|
|
404:
|
|
description: Project does not exist.
|
|
412:
|
|
description: Project contains policies, can not be deleted.
|
|
500:
|
|
description: Internal errors.
|
|
/projects/{project_id}/publicity:
|
|
put:
|
|
summary: Update properties for a selected project.
|
|
description: |
|
|
This endpoint is aimed to toggle a project publicity status.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Selected project ID.
|
|
- name: project
|
|
in: body
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/Project'
|
|
description: Updates of project.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Updated project publicity status successfully.
|
|
400:
|
|
description: Illegal format of provided ID value.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User does not have permission to the project.
|
|
404:
|
|
description: Project ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/projects/{project_id}/logs/filter:
|
|
post:
|
|
summary: Get access logs accompany with a relevant project.
|
|
description: |
|
|
This endpoint let user search access logs filtered by operations and date time ranges.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Relevant project ID
|
|
- name: access_log
|
|
in: body
|
|
schema:
|
|
$ref: '#/definitions/AccessLogFilter'
|
|
description: Search results of access logs.
|
|
- name: page
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The page nubmer, default is 1.
|
|
- name: page_size
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The size of per page, default is 10, maximum is 100.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get access log successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/AccessLog'
|
|
headers:
|
|
X-Total-Count:
|
|
description: The total count of access logs
|
|
type: integer
|
|
Link:
|
|
description: Link refers to the previous page and next page
|
|
type: string
|
|
400:
|
|
description: Illegal format of provided ID value.
|
|
401:
|
|
description: User need to log in first.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/projects/{project_id}/members/:
|
|
get:
|
|
summary: Return a project's relevant role members.
|
|
description: |
|
|
This endpoint is for user to search a specified project's relevant role members.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Relevant project ID.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get project's relevant role members successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/User'
|
|
400:
|
|
description: Illegal format of provided ID value.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User in session does not have permission to the project.
|
|
404:
|
|
description: Project ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
post:
|
|
summary: Add project role member accompany with relevant project and user.
|
|
description: |
|
|
This endpoint is for user to add project role member accompany with relevant project and user.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Relevant project ID.
|
|
- name: roles
|
|
in: body
|
|
description: Role members for adding to relevant project. Only one role is supported in the role list.
|
|
schema:
|
|
$ref: '#/definitions/RoleParam'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Role members added to relevant project successfully.
|
|
400:
|
|
description: Illegal format of provided ID value.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User in session does not have permission to the project.
|
|
404:
|
|
description: Project ID or username does not exist.
|
|
409:
|
|
description: User has already added as a project role member.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/projects/{project_id}/members/{user_id}:
|
|
get:
|
|
summary: Return role members accompany with relevant project and user.
|
|
description: |
|
|
This endpoint is for user to get role members accompany with relevant project and user.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Relevant project ID
|
|
- name: user_id
|
|
in: path
|
|
type: integer
|
|
format: int
|
|
required: true
|
|
description: Relevant user ID
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get project role members successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/Role'
|
|
400:
|
|
description: Illegal format of provided ID value.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User in session does not have permission to the project.
|
|
404:
|
|
description: Project ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
put:
|
|
summary: Update project role members accompany with relevant project and user.
|
|
description: |
|
|
This endpoint is for user to update current project role members accompany with relevant project and user.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Relevant project ID.
|
|
- name: user_id
|
|
in: path
|
|
type: integer
|
|
format: int
|
|
required: true
|
|
description: Relevant user ID.
|
|
- name: roles
|
|
in: body
|
|
schema:
|
|
$ref: '#/definitions/RoleParam'
|
|
description: Updates for roles and username.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Project role members updated successfully.
|
|
400:
|
|
description: Illegal format of provided ID value.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User in session does not have permission to the project.
|
|
404:
|
|
description: Project ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
delete:
|
|
summary: Delete project role members accompany with relevant project and user.
|
|
description: |
|
|
This endpoint is aimed to remove project role members already added to the relevant project and user.
|
|
parameters:
|
|
- name: project_id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Relevant project ID.
|
|
- name: user_id
|
|
in: path
|
|
type: integer
|
|
format: int
|
|
required: true
|
|
description: Relevant user ID.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Project role members deleted successfully.
|
|
400:
|
|
description: Illegal format of provided ID value.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User in session does not have permission to the project.
|
|
404:
|
|
description: Project ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/statistics:
|
|
get:
|
|
summary: Get projects number and repositories number relevant to the user
|
|
description: |
|
|
This endpoint is aimed to statistic all of the projects number and repositories number relevant to the logined user, also the public projects number and repositories number. If the user is admin, he can also get total projects number and total repositories number.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get the projects number and repositories number relevant to the user successfully.
|
|
schema:
|
|
$ref: '#/definitions/StatisticMap'
|
|
401:
|
|
description: User need to log in first.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
|
|
/users:
|
|
get:
|
|
summary: Get registered users of Harbor.
|
|
description: |
|
|
This endpoint is for user to search registered users, support for filtering results with username.Notice, by now this operation is only for administrator.
|
|
parameters:
|
|
- name: username
|
|
in: query
|
|
type: string
|
|
required: false
|
|
description: Username for filtering results.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Searched for users of Harbor successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/User'
|
|
400:
|
|
description: Invalid user ID.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User does not have permission of admin role.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
post:
|
|
summary: Creates a new user account.
|
|
description: |
|
|
This endpoint is to create a user if the user does not already exist.
|
|
parameters:
|
|
- name: user
|
|
in: body
|
|
description: New created user.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/User'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
201:
|
|
description: User created successfully.
|
|
400:
|
|
description: Unsatisfied with constraints of the user creation.
|
|
403:
|
|
description: User registration can only be used by admin role user when self-registration is off.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/users/{user_id}:
|
|
put:
|
|
summary: Update a registered user to change his profile.
|
|
description: |
|
|
This endpoint let a registered user change his profile.
|
|
parameters:
|
|
- name: user_id
|
|
in: path
|
|
type: integer
|
|
format: int
|
|
required: true
|
|
description: Registered user ID
|
|
- name: profile
|
|
in: body
|
|
description: Only email, realname and comment can be modified.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/UserProfile'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Updated user's admin role successfully.
|
|
400:
|
|
description: Invalid user ID.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User does not have permission of admin role.
|
|
404:
|
|
description: User ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
delete:
|
|
summary: Mark a registered user as be removed.
|
|
description: |
|
|
This endpoint let administrator of Harbor mark a registered user as
|
|
be removed.It actually won't be deleted from DB.
|
|
parameters:
|
|
- name: user_id
|
|
in: path
|
|
type: integer
|
|
format: int
|
|
required: true
|
|
description: User ID for marking as to be removed.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Marked user as be removed successfully.
|
|
400:
|
|
description: Invalid user ID.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User does not have permission of admin role.
|
|
404:
|
|
description: User ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/users/{user_id}/password:
|
|
put:
|
|
summary: Change the password on a user that already exists.
|
|
description: |
|
|
This endpoint is for user to update password. Users with the admin role can change any user's password. Guest users can change only their own password.
|
|
parameters:
|
|
- name: user_id
|
|
in: path
|
|
type: integer
|
|
format: int
|
|
required: true
|
|
description: Registered user ID.
|
|
- name: password
|
|
in: body
|
|
description: Password to be updated.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/Password'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Updated password successfully.
|
|
400:
|
|
description: Invalid user ID; Old password is blank; New password is blank.
|
|
401:
|
|
description: Don't have authority to change password. Please check login status.
|
|
403:
|
|
description: Old password is not correct.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/users/{user_id}/sysadmin:
|
|
put:
|
|
summary: Update a registered user to change to be an administrator of Harbor.
|
|
description: |
|
|
This endpoint let a registered user change to be an administrator
|
|
of Harbor.
|
|
parameters:
|
|
- name: user_id
|
|
in: path
|
|
type: integer
|
|
format: int
|
|
required: true
|
|
description: Registered user ID
|
|
- name: has_admin_role
|
|
in: body
|
|
description: Toggle a user to admin or not.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/HasAdminRole'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Updated user's admin role successfully.
|
|
400:
|
|
description: Invalid user ID.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User does not have permission of admin role.
|
|
404:
|
|
description: User ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/repositories:
|
|
get:
|
|
summary: Get repositories accompany with relevant project and repo name.
|
|
description: |
|
|
This endpoint let user search repositories accompanying with relevant project ID and repo name.
|
|
parameters:
|
|
- name: project_id
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: true
|
|
description: Relevant project ID.
|
|
- name: q
|
|
in: query
|
|
type: string
|
|
required: false
|
|
description: Repo name for filtering results.
|
|
- name: page
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The page nubmer, default is 1.
|
|
- name: page_size
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The size of per page, default is 10, maximum is 100.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Searched for respositories successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
headers:
|
|
X-Total-Count:
|
|
description: The total count of repositories
|
|
type: integer
|
|
Link:
|
|
description: Link refers to the previous page and next page
|
|
type: string
|
|
400:
|
|
description: Invalid project ID.
|
|
403:
|
|
description: Project is not public or current user is irrelevant to the repository.
|
|
404:
|
|
description: Project ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
delete:
|
|
summary: Delete a repository or a tag in a repository.
|
|
description: |
|
|
This endpoint let user delete repositories and tags with repo name and tag.
|
|
parameters:
|
|
- name: repo_name
|
|
in: query
|
|
type: string
|
|
required: true
|
|
description: The name of repository which will be deleted.
|
|
- name: tag
|
|
in: query
|
|
type: string
|
|
required: false
|
|
description: Tag of a repository.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Delete repository or tag successfully.
|
|
400:
|
|
description: Invalid repo_name.
|
|
401:
|
|
description: Unauthorized.
|
|
404:
|
|
description: Repository or tag not found.
|
|
403:
|
|
description: Forbidden.
|
|
/repositories/tags:
|
|
get:
|
|
summary: Get tags of a relevant repository.
|
|
description: |
|
|
This endpoint aims to retrieve tags from a relevant repository.
|
|
parameters:
|
|
- name: repo_name
|
|
in: query
|
|
type: string
|
|
required: true
|
|
description: Relevant repository name.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Retrieved tags from a relevant repository successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/repositories/manifests:
|
|
get:
|
|
summary: Get manifests of a relevant repository.
|
|
description: |
|
|
This endpoint aims to retreive manifests from a relevant repository.
|
|
parameters:
|
|
- name: repo_name
|
|
in: query
|
|
type: string
|
|
required: true
|
|
description: Repository name
|
|
- name: tag
|
|
in: query
|
|
type: string
|
|
required: true
|
|
description: Tag name
|
|
- name: version
|
|
in: query
|
|
type: string
|
|
required: false
|
|
description: The version of manifest, valid value are "v1" and "v2", default is "v2"
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Retrieved manifests from a relevant repository successfully.
|
|
schema:
|
|
$ref: '#/definitions/Repository'
|
|
404:
|
|
description: Retrieved manifests from a relevant repository not found.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/repositories/top:
|
|
get:
|
|
summary: Get public repositories which are accessed most.
|
|
description: |
|
|
This endpoint aims to let users see the most popular public repositories
|
|
parameters:
|
|
- name: count
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The number of the requested public repositories, default is 10 if not provided.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Retrieved top repositories successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/TopRepo'
|
|
400:
|
|
description: Bad request because of invalid count.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/logs:
|
|
get:
|
|
summary: Get recent logs of the projects which the user is a member of
|
|
description: |
|
|
This endpoint let user see the recent operation logs of the projects which he is member of
|
|
parameters:
|
|
- name: lines
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The number of logs to be shown, default is 10 if lines, start_time, end_time are not provided.
|
|
- name: start_time
|
|
in: query
|
|
type: integer
|
|
format: int64
|
|
required: false
|
|
description: The start time of logs to be shown in unix timestap
|
|
- name: end_time
|
|
in: query
|
|
type: integer
|
|
format: int64
|
|
required: false
|
|
description: The end time of logs to be shown in unix timestap
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get the required logs successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/AccessLog'
|
|
400:
|
|
description: Bad request because of invalid parameter of lines or start_time or end_time.
|
|
401:
|
|
description: User need to login first.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/jobs/replication:
|
|
get:
|
|
summary: List filters jobs according to the policy and repository
|
|
description: |
|
|
This endpoint let user list filters jobs according to the policy and repository. (if start_time and end_time are both null, list jobs of last 10 days)
|
|
tags:
|
|
- Products
|
|
parameters:
|
|
- name: policy_id
|
|
in: query
|
|
type: integer
|
|
format: int
|
|
required: false
|
|
description: The ID of the policy that triggered this job.
|
|
- name: num
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The return list length number.
|
|
- name: end_time
|
|
in: query
|
|
type: integer
|
|
format: int64
|
|
required: false
|
|
description: The end time of jobs done. (Timestamp)
|
|
- name: start_time
|
|
in: query
|
|
type: integer
|
|
format: int64
|
|
required: false
|
|
description: The start time of jobs. (Timestamp)
|
|
- name: repository
|
|
in: query
|
|
type: string
|
|
required: false
|
|
description: The respond jobs list filter by repository name.
|
|
- name: status
|
|
in: query
|
|
type: string
|
|
required: false
|
|
description: The respond jobs list filter by status.
|
|
- name: page
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The page nubmer, default is 1.
|
|
- name: page_size
|
|
in: query
|
|
type: integer
|
|
format: int32
|
|
required: false
|
|
description: The size of per page, default is 10, maximum is 100.
|
|
responses:
|
|
200:
|
|
description: Get the required logs successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/RepPolicy'
|
|
headers:
|
|
X-Total-Count:
|
|
description: The total count of jobs
|
|
type: integer
|
|
Link:
|
|
description: Link refers to the previous page and next page
|
|
type: string
|
|
400:
|
|
description: Bad request because of invalid parameters.
|
|
401:
|
|
description: User need to login first.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/jobs/replication/{id}:
|
|
delete:
|
|
summary: Delete specific ID job.
|
|
description: |
|
|
This endpoint is aimed to remove specific ID job from jobservice.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Delete job ID.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Job deleted successfully.
|
|
400:
|
|
description: Job ID is invalid or can't remove this job.
|
|
401:
|
|
description: Only admin has this authority.
|
|
404:
|
|
description: Project ID does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/jobs/replication/{id}/log:
|
|
get:
|
|
summary: Get job logs.
|
|
description: |
|
|
This endpoint let user search job logs filtered by specific ID.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: Relevant repository ID
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get job log successfully.
|
|
400:
|
|
description: Illegal format of provided ID value.
|
|
401:
|
|
description: User need to log in first.
|
|
404:
|
|
description: The specific repository ID's log does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/policies/replication:
|
|
get:
|
|
summary: List filters policies by name and project_id
|
|
description: |
|
|
This endpoint let user list filters policies by name and project_id, if name and project_id are nil, list returns all policies
|
|
parameters:
|
|
- name: name
|
|
in: query
|
|
type: string
|
|
required: false
|
|
description: The replication's policy name.
|
|
- name: project_id
|
|
in: query
|
|
type: integer
|
|
format: int64
|
|
required: false
|
|
description: Relevant project ID.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get policy successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/JobStatus'
|
|
400:
|
|
description: Invalid project ID.
|
|
401:
|
|
description: User need to log in first.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
post:
|
|
summary: Post creates a policy
|
|
description: |
|
|
This endpoint let user creates a policy, and if it is enabled, the replication will be triggered right now.
|
|
parameters:
|
|
- name: policyinfo
|
|
in: body
|
|
description: Create new policy.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/RepPolicyPost'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
201:
|
|
description: Create policy successfully.
|
|
400:
|
|
description: Invalid project ID or target ID.
|
|
401:
|
|
description: User need to log in first.
|
|
409:
|
|
description: Policy name already used or policy already exists with the same project and target.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/policies/replication/{id}:
|
|
get:
|
|
summary: Get replication policy.
|
|
description: |
|
|
This endpoint let user search replication policy by specific ID.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: policy ID
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get job policy successfully.
|
|
schema:
|
|
$ref: '#/definitions/RepPolicy'
|
|
401:
|
|
description: User need to log in first.
|
|
404:
|
|
description: The specific repository ID's policy does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
put:
|
|
summary: Put modifies name, description, target and enablement of policy.
|
|
description: |
|
|
This endpoint let user update policy name, description, target and enablement.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: policy ID
|
|
- name: policyupdate
|
|
in: body
|
|
description: Update policy name, description, target and enablement.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/RepPolicyUpdate'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Update job policy content successfully.
|
|
400:
|
|
description: policy is enabled or target does not exist
|
|
401:
|
|
description: User need to log in first.
|
|
404:
|
|
description: The specific repository ID's policy does not exist.
|
|
409:
|
|
description: Policy name already used or policy already exists with the same project and target.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/policies/replication/{id}/enablement:
|
|
put:
|
|
summary: Put modifies enablement of the policy.
|
|
description: |
|
|
This endpoint let user update policy enablement flag.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: policy ID
|
|
- name: enabledflag
|
|
in: body
|
|
description: The policy enablement flag.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/RepPolicyEnablementReq'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Update job policy enablement successfully.
|
|
400:
|
|
description: Invalid enabled value.
|
|
401:
|
|
description: User need to log in first.
|
|
404:
|
|
description: The specific repository ID's policy does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/targets:
|
|
get:
|
|
summary: List filters targets by name.
|
|
description: |
|
|
This endpoint let user list filters targets by name, if name is nil, list returns all targets.
|
|
parameters:
|
|
- name: name
|
|
in: query
|
|
type: string
|
|
required: false
|
|
description: The replication's target name.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get policy successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/RepTarget'
|
|
401:
|
|
description: User need to log in first.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
post:
|
|
summary: Create a new replication target.
|
|
description: |
|
|
This endpoint is for user to create a new replication target.
|
|
parameters:
|
|
- name: reptarget
|
|
in: body
|
|
description: New created replication target.
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/RepTargetPost'
|
|
tags:
|
|
- Products
|
|
responses:
|
|
201:
|
|
description: Replication target created successfully.
|
|
400:
|
|
description: Unsatisfied with constraints of the target creation.
|
|
401:
|
|
description: User need to log in first.
|
|
409:
|
|
description: Replication target name already exists.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/targets/ping:
|
|
post:
|
|
summary: Ping validates target.
|
|
description: |
|
|
This endpoint is for ping validates whether the target is reachable and whether the credential is valid.
|
|
parameters:
|
|
- name: id
|
|
in: query
|
|
type: integer
|
|
format: int64
|
|
required: false
|
|
description: The replication's policy ID.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Ping target successfully.
|
|
400:
|
|
description: Target id is invalid/ endpoint is needed/ invaild URL/ network issue.
|
|
401:
|
|
description: User need to log in first or wrong username/password for remote target.
|
|
404:
|
|
description: Target not found.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/targets/{id}:
|
|
put:
|
|
summary: Update replication's target.
|
|
description: |
|
|
This endpoint is for update specific replication's target.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: The replication's target ID.
|
|
- name: repo_target
|
|
in: body
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/RepTargetPost'
|
|
description: Updates of replication's target.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Updated replication's target successfully.
|
|
400:
|
|
description: The target is associated with policy which is enabled.
|
|
401:
|
|
description: User need to log in first.
|
|
404:
|
|
description: Target ID does not exist.
|
|
409:
|
|
description: Target name or endpoint is already used.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
get:
|
|
summary: Get replication's target.
|
|
description: This endpoint is for get specific replication's target.
|
|
tags:
|
|
- Products
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: The replication's target ID.
|
|
responses:
|
|
200:
|
|
description: Get replication's target successfully.
|
|
schema:
|
|
$ref: '#/definitions/RepTarget'
|
|
401:
|
|
description: User need to log in first.
|
|
404:
|
|
description: Replication's target not found
|
|
500:
|
|
description: Unexpected internal errors.
|
|
delete:
|
|
summary: Delete specific replication's target.
|
|
description: |
|
|
This endpoint is for to delete specific replication's target.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: The replication's target ID.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Replication's target deleted successfully.
|
|
400:
|
|
description: Replication's target ID is invalid or the target is used by policies.
|
|
401:
|
|
description: Only admin has this authority.
|
|
404:
|
|
description: Replication's target does not exist.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/targets/{id}/policies/:
|
|
get:
|
|
summary: List the target relevant policies.
|
|
description: |
|
|
This endpoint list policies filter with specific replication's target ID.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
type: integer
|
|
format: int64
|
|
required: true
|
|
description: The replication's target ID.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Get relevant policies successfully.
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/RepPolicy'
|
|
401:
|
|
description: User need to log in first.
|
|
404:
|
|
description: Replication's target not found
|
|
500:
|
|
description: Unexpected internal errors.
|
|
/internal/syncregistry:
|
|
post:
|
|
summary: Sync repositories from registry to DB.
|
|
description: |
|
|
This endpoint is for syncing all repositories of registry with database.
|
|
tags:
|
|
- Products
|
|
responses:
|
|
200:
|
|
description: Sync repositories successfully.
|
|
401:
|
|
description: User need to log in first.
|
|
403:
|
|
description: User does not have permission of admin role.
|
|
500:
|
|
description: Unexpected internal errors.
|
|
definitions:
|
|
Search:
|
|
type: object
|
|
properties:
|
|
projects:
|
|
description: Search results of the projects that matched the filter keywords.
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/SearchProject'
|
|
repositories:
|
|
description: Search results of the repositories that matched the filter keywords.
|
|
type: array
|
|
items:
|
|
$ref: '#/definitions/SearchRepository'
|
|
SearchProject:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: The ID of project
|
|
name:
|
|
type: string
|
|
description: The name of the project
|
|
public:
|
|
type: integer
|
|
format: int
|
|
description: The flag to indicate the publicity of the project (1 is public, 0 is non-public)
|
|
SearchRepository:
|
|
type: object
|
|
properties:
|
|
project_id:
|
|
type: integer
|
|
description: The ID of the project that the repository belongs to
|
|
project_name:
|
|
type: string
|
|
description: The name of the project that the repository belongs to
|
|
project_public:
|
|
type: integer
|
|
description: The flag to indicate the publicity of the project that the repository belongs to (1 is public, 0 is not)
|
|
repository_name:
|
|
type: string
|
|
description: The name of the repository
|
|
ProjectReq:
|
|
type: object
|
|
properties:
|
|
project_name:
|
|
type: string
|
|
description: The name of the project.
|
|
public:
|
|
type: integer
|
|
format: int
|
|
description: The public status of the project.
|
|
Project:
|
|
type: object
|
|
properties:
|
|
project_id:
|
|
type: integer
|
|
format: int32
|
|
description: Project ID
|
|
owner_id:
|
|
type: integer
|
|
format: int32
|
|
description: The owner ID of the project always means the creator of the project.
|
|
name:
|
|
type: string
|
|
description: The name of the project.
|
|
creation_time:
|
|
type: string
|
|
description: The creation time of the project.
|
|
update_time:
|
|
type: string
|
|
description: The update time of the project.
|
|
deleted:
|
|
type: integer
|
|
format: int32
|
|
description: A deletion mark of the project (1 means it's deleted, 0 is not)
|
|
owner_name:
|
|
type: string
|
|
description: The owner name of the project.
|
|
public:
|
|
type: integer
|
|
format: int
|
|
description: The public status of the project.
|
|
Togglable:
|
|
type: boolean
|
|
description: Correspond to the UI about whether the project's publicity is updatable (for UI)
|
|
current_user_role_id:
|
|
type: integer
|
|
description: The role ID of the current user who triggered the API (for UI)
|
|
repo_count:
|
|
type: integer
|
|
description: The number of the repositories under this project.
|
|
Repository:
|
|
type: object
|
|
properties:
|
|
manifest:
|
|
type: object
|
|
description: The detail of manifest.
|
|
config:
|
|
type: string
|
|
description: The config of the repository.
|
|
User:
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
format: int
|
|
description: The ID of the user.
|
|
username:
|
|
type: string
|
|
email:
|
|
type: string
|
|
password:
|
|
type: string
|
|
realname:
|
|
type: string
|
|
comment:
|
|
type: string
|
|
deleted:
|
|
type: integer
|
|
format: int32
|
|
role_name:
|
|
type: string
|
|
role_id:
|
|
type: integer
|
|
format: int
|
|
has_admin_role:
|
|
type: integer
|
|
format: int
|
|
reset_uuid:
|
|
type: string
|
|
Salt:
|
|
type: string
|
|
creation_time:
|
|
type: string
|
|
update_time:
|
|
type: string
|
|
Password:
|
|
type: object
|
|
properties:
|
|
old_password:
|
|
type: string
|
|
description: The user's existing password.
|
|
new_password:
|
|
type: string
|
|
description: New password for marking as to be updated.
|
|
AccessLogFilter:
|
|
type: object
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: Relevant user's name that accessed this project.
|
|
keywords:
|
|
type: string
|
|
description: Operation name specified when project created.
|
|
begin_timestamp:
|
|
type: integer
|
|
format: int64
|
|
description: Begin timestamp for querying access logs.
|
|
end_timestamp:
|
|
type: integer
|
|
format: int64
|
|
description: End timestamp for querying accessl logs.
|
|
AccessLog:
|
|
type: object
|
|
properties:
|
|
log_id:
|
|
type: integer
|
|
description: The ID of the log entry.
|
|
repo_name:
|
|
type: string
|
|
description: Name of the repository in this log entry.
|
|
repo_tag:
|
|
type: string
|
|
description: Tag of the repository in this log entry.
|
|
operation:
|
|
type: string
|
|
description: The operation against the repository in this log entry.
|
|
op_time:
|
|
type: string
|
|
description: The time when this operation is triggered.
|
|
Role:
|
|
type: object
|
|
properties:
|
|
role_id:
|
|
type: integer
|
|
format: int32
|
|
description: ID in table.
|
|
role_code:
|
|
type: string
|
|
description: Description of permissions for the role.
|
|
role_name:
|
|
type: string
|
|
description: Name the the role.
|
|
role_mask:
|
|
type: string
|
|
RoleParam:
|
|
type: object
|
|
properties:
|
|
roles:
|
|
type: array
|
|
items:
|
|
type: integer
|
|
format: int32
|
|
description: Role ID for updating project role member.
|
|
username:
|
|
type: string
|
|
description: Username relevant to a project role member.
|
|
TopRepo:
|
|
type: object
|
|
properties:
|
|
repo_name:
|
|
type: string
|
|
description: The name of the repo
|
|
count:
|
|
type: integer
|
|
format: int
|
|
description: The access count of the repo
|
|
StatisticMap:
|
|
type: object
|
|
properties:
|
|
my_project_count:
|
|
type: integer
|
|
format: int32
|
|
description: The count of the projects which the user is a member of.
|
|
my_repo_count:
|
|
type: integer
|
|
format: int32
|
|
description: The count of the repositories belonging to the projects which the user is a member of.
|
|
public_project_count:
|
|
type: integer
|
|
format: int32
|
|
description: The count of the public projects.
|
|
public_repo_count:
|
|
type: integer
|
|
format: int32
|
|
description: The count of the public repositories belonging to the public projects which the user is a member of.
|
|
total_project_count:
|
|
type: integer
|
|
format: int32
|
|
description: The count of the total projects, only be seen when the is admin.
|
|
total_repo_count:
|
|
type: integer
|
|
format: int32
|
|
description: The count of the total repositories, only be seen when the user is admin.
|
|
JobStatus:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: The job ID.
|
|
status:
|
|
type: string
|
|
description: The status of the job.
|
|
repository:
|
|
type: string
|
|
description: The repository handled by the job.
|
|
policy_id:
|
|
type: integer
|
|
format: int64
|
|
description: The ID of the policy that triggered this job.
|
|
operation:
|
|
type: string
|
|
description: The operation of the job.
|
|
tags:
|
|
type: array
|
|
description: The repository's used tag list.
|
|
items:
|
|
$ref: '#/definitions/Tags'
|
|
creation_time:
|
|
type: string
|
|
description: The creation time of the job.
|
|
update_time:
|
|
type: string
|
|
description: The update time of the job.
|
|
Tags:
|
|
type: object
|
|
properties:
|
|
tag:
|
|
type: string
|
|
description: The repository's used tag.
|
|
RepPolicy:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: The policy ID.
|
|
project_id:
|
|
type: integer
|
|
format: int64
|
|
description: The project ID.
|
|
project_name:
|
|
type: string
|
|
description: The project name.
|
|
target_id:
|
|
type: integer
|
|
format: int64
|
|
description: The target ID.
|
|
name:
|
|
type: string
|
|
description: The policy name.
|
|
enabled:
|
|
type: integer
|
|
format: int
|
|
description: The policy's enabled status.
|
|
description:
|
|
type: string
|
|
description: The description of the policy.
|
|
cron_str:
|
|
type: string
|
|
description: The cron string for schedule job.
|
|
start_time:
|
|
type: string
|
|
description: The start time of the policy.
|
|
creation_time:
|
|
type: string
|
|
description: The create time of the policy.
|
|
update_time:
|
|
type: string
|
|
description: The update time of the policy.
|
|
error_job_count:
|
|
format: int
|
|
description: The error job count number for the policy.
|
|
deleted:
|
|
type: integer
|
|
RepPolicyPost:
|
|
type: object
|
|
properties:
|
|
project_id:
|
|
type: integer
|
|
format: int64
|
|
description: The project ID.
|
|
target_id:
|
|
type: integer
|
|
format: int64
|
|
description: The target ID.
|
|
name:
|
|
type: string
|
|
description: The policy name.
|
|
RepPolicyUpdate:
|
|
type: object
|
|
properties:
|
|
target_id:
|
|
type: integer
|
|
format: int64
|
|
description: The target ID.
|
|
name:
|
|
type: string
|
|
description: The policy name.
|
|
enabled:
|
|
type: integer
|
|
format: int
|
|
description: The policy's enabled status.
|
|
description:
|
|
type: string
|
|
description: The description of the policy.
|
|
cron_str:
|
|
type: string
|
|
description: The cron string for schedule job.
|
|
RepPolicyEnablementReq:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: integer
|
|
format: int
|
|
description: The policy enablement flag.
|
|
RepTarget:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
format: int64
|
|
description: The target ID.
|
|
endpoint:
|
|
type: string
|
|
description: The target address URL string.
|
|
name:
|
|
type: string
|
|
description: The target name.
|
|
username:
|
|
type: string
|
|
description: The target server username.
|
|
password:
|
|
type: string
|
|
description: The target server password.
|
|
type:
|
|
type: integer
|
|
format: int
|
|
description: Reserved field.
|
|
creation_time:
|
|
type: string
|
|
description: The create time of the policy.
|
|
update_time:
|
|
type: string
|
|
description: The update time of the policy.
|
|
RepTargetPost:
|
|
type: object
|
|
properties:
|
|
endpoint:
|
|
type: string
|
|
description: The target address URL string.
|
|
name:
|
|
type: string
|
|
description: The target name.
|
|
username:
|
|
type: string
|
|
description: The target server username.
|
|
password:
|
|
type: string
|
|
description: The target server password.
|
|
HasAdminRole:
|
|
type: object
|
|
properties:
|
|
has_admin_role:
|
|
type: integer
|
|
description: 1-has admin, 0-not.
|
|
UserProfile:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
description: The new email.
|
|
realname:
|
|
type: string
|
|
description: The new realname.
|
|
comment:
|
|
type: string
|
|
description: The new comment.
|