# 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 format: 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 format: string - name: is_public in: query description: Public sign for filtering projects. required: false type: integer format: int32 tags: - Products responses: 200: description: Return all matched projects. schema: type: array items: $ref: '#/definitions/Project' 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 format: 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/Project' 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}/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: int32 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: int32 required: true description: Relevant project ID - name: access_log in: body schema: $ref: '#/definitions/AccessLogFilter' description: Search results of access logs. tags: - Products responses: 200: description: Get access log successfully. schema: type: array items: $ref: '#/definitions/AccessLog' 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: int32 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: int32 required: true description: Relevant project ID. - name: roles in: body description: Role members for adding to relevant project. 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: int32 required: true description: Relevant project ID - name: user_id in: path type: integer format: int32 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: int32 required: true description: Relevant project ID. - name: user_id in: path type: integer format: int32 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: int32 required: true description: Relevant project ID. - name: user_id in: path type: integer format: int32 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: user_name in: query type: string format: 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: int32 required: true description: Registered user ID - name: profile in: body description: Only email, realname and comment can be modified. required: true schema: $ref: '#/definitions/User' 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: int32 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: int32 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: Old password is not correct. 403: description: Guests can only change their own account. 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: int32 required: true description: Registered user ID 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 format: string required: false description: Repo name for filtering results. tags: - Products responses: 200: description: Searched for respositories successfully. schema: type: array items: 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 format: string required: true description: The name of repository which will be deleted. - name: tag in: query type: string format: 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. 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 tags: - Products responses: 200: description: Retrieved manifests from a relevant repository successfully. 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. 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: repository_name: type: string description: The name of the repository project_name: type: string description: The name of the project that the repository belongs to project_id: type: integer description: The ID 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) 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) user_id: type: integer format: int32 description: A relation field to the user table. owner_name: type: string description: The owner name of the project. public: type: boolean format: boolean 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. User: type: object properties: user_id: type: integer format: int32 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 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. 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 access_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.