harbor/docs/swagger.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.1.1"
# 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}:
    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.
  Repository:
    type: object
    properties:
      id:
        type: string
        description: Repository ID
      parent:
        type: string
        description: Parent of the image.
      created:
        type: string
        format: date-time
        description: Repository create time.
      duration_days:
        type: string
        description: Duration days of the image.
      author:
        type: string
        description: Author of the image.
      architecture:
        type: string
        description: Architecture of the image.
      docker_version:
        type: string
        description: Docker version of the image.
      os:
        type: string
        description: OS of the image.
  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: time
        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.