openapi: 3.0.0
info:
  title: Launchpad REST API
  description: >-
    The Launchpad web service API provides REST-based access to Launchpad's
    resources including people, projects, bugs, branches, and packages.
    The canonical source for the full API is the WADL document at api.launchpad.net.
  version: "1.0"
  contact:
    name: Launchpad Community
    url: https://help.launchpad.net/API
servers:
  - url: https://api.launchpad.net/1.0
    description: Launchpad Production API
  - url: https://api.staging.launchpad.net/1.0
    description: Launchpad Staging API
security:
  - OAuth1: []
tags:
  - name: People
    description: People and team resources
  - name: Projects
    description: Open-source project resources
  - name: Bugs
    description: Bug tracking and management
  - name: Packages
    description: Distribution package management
  - name: Distributions
    description: Ubuntu distribution resources
paths:
  /people:
    get:
      operationId: listPeople
      summary: List People
      description: Returns a collection of people and teams registered in Launchpad.
      tags:
        - People
      parameters:
        - name: ws.op
          in: query
          required: false
          schema:
            type: string
          description: Named operation to perform on the collection.
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Search query string for people.
        - name: ws.start
          in: query
          required: false
          schema:
            type: integer
          description: Starting offset for pagination.
        - name: ws.size
          in: query
          required: false
          schema:
            type: integer
          description: Number of items to return.
      responses:
        '200':
          description: Collection of people.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonCollection'

  /~{person_name}:
    get:
      operationId: getPerson
      summary: Get Person
      description: Returns information about a specific Launchpad person or team.
      tags:
        - People
      parameters:
        - name: person_name
          in: path
          required: true
          schema:
            type: string
          description: Launchpad username or team name.
      responses:
        '200':
          description: Person or team details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '404':
          description: Person not found.

  /bugs:
    get:
      operationId: listBugs
      summary: List Bugs
      description: Returns a collection of bugs tracked in Launchpad.
      tags:
        - Bugs
      parameters:
        - name: ws.op
          in: query
          required: false
          schema:
            type: string
          description: Named operation to perform.
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: Filter bugs by status.
        - name: ws.start
          in: query
          required: false
          schema:
            type: integer
          description: Starting offset for pagination.
        - name: ws.size
          in: query
          required: false
          schema:
            type: integer
          description: Number of items per page.
      responses:
        '200':
          description: Collection of bugs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BugCollection'

  /bugs/{bug_id}:
    get:
      operationId: getBug
      summary: Get Bug
      description: Returns details for a specific Launchpad bug.
      tags:
        - Bugs
      parameters:
        - name: bug_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique bug identifier.
      responses:
        '200':
          description: Bug details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bug'
        '404':
          description: Bug not found.
    patch:
      operationId: updateBug
      summary: Update Bug
      description: Update a bug's fields such as title, description, or status.
      tags:
        - Bugs
      parameters:
        - name: bug_id
          in: path
          required: true
          schema:
            type: integer
          description: Unique bug identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated bug.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bug'

  /projects:
    get:
      operationId: listProjects
      summary: List Projects
      description: Returns a collection of projects registered in Launchpad.
      tags:
        - Projects
      parameters:
        - name: ws.op
          in: query
          required: false
          schema:
            type: string
        - name: q
          in: query
          required: false
          schema:
            type: string
          description: Project search query.
        - name: ws.start
          in: query
          required: false
          schema:
            type: integer
        - name: ws.size
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Collection of projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCollection'

  /{project_name}:
    get:
      operationId: getProject
      summary: Get Project
      description: Returns details for a specific Launchpad project.
      tags:
        - Projects
      parameters:
        - name: project_name
          in: path
          required: true
          schema:
            type: string
          description: Launchpad project name.
      responses:
        '200':
          description: Project details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          description: Project not found.

  /ubuntu:
    get:
      operationId: getUbuntuDistribution
      summary: Get Ubuntu Distribution
      description: Returns information about the Ubuntu distribution in Launchpad.
      tags:
        - Distributions
      responses:
        '200':
          description: Ubuntu distribution details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Distribution'

  /ubuntu/+source/{source_package_name}:
    get:
      operationId: getSourcePackage
      summary: Get Source Package
      description: Returns details for a specific Ubuntu source package.
      tags:
        - Packages
      parameters:
        - name: source_package_name
          in: path
          required: true
          schema:
            type: string
          description: Source package name.
      responses:
        '200':
          description: Source package details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcePackage'
        '404':
          description: Source package not found.

components:
  securitySchemes:
    OAuth1:
      type: http
      scheme: oauth
      description: OAuth 1.0a authentication with Launchpad credentials
  schemas:
    Person:
      type: object
      properties:
        name:
          type: string
          description: Launchpad username.
        display_name:
          type: string
          description: Display name.
        email_addresses_collection_link:
          type: string
          format: uri
          description: Link to the person's email addresses.
        bugs_reported_collection_link:
          type: string
          format: uri
        teams_participated_in_collection_link:
          type: string
          format: uri
        web_link:
          type: string
          format: uri
        self_link:
          type: string
          format: uri

    PersonCollection:
      type: object
      properties:
        total_size:
          type: integer
        start:
          type: integer
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Person'

    Bug:
      type: object
      properties:
        id:
          type: integer
          description: Unique bug identifier.
        title:
          type: string
          description: Bug title.
        description:
          type: string
          description: Full bug description.
        status:
          type: string
          description: Current bug status.
        importance:
          type: string
          description: Bug importance level.
        tags:
          type: array
          items:
            type: string
        date_created:
          type: string
          format: date-time
        date_last_updated:
          type: string
          format: date-time
        web_link:
          type: string
          format: uri
        self_link:
          type: string
          format: uri

    BugCollection:
      type: object
      properties:
        total_size:
          type: integer
        start:
          type: integer
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Bug'

    Project:
      type: object
      properties:
        name:
          type: string
          description: Project name identifier.
        display_name:
          type: string
          description: Project display name.
        title:
          type: string
          description: Project title.
        summary:
          type: string
          description: One-line project summary.
        description:
          type: string
          description: Full project description.
        homepage_url:
          type: string
          format: uri
        programming_language:
          type: string
        web_link:
          type: string
          format: uri
        self_link:
          type: string
          format: uri

    ProjectCollection:
      type: object
      properties:
        total_size:
          type: integer
        start:
          type: integer
        entries:
          type: array
          items:
            $ref: '#/components/schemas/Project'

    Distribution:
      type: object
      properties:
        name:
          type: string
          description: Distribution name.
        display_name:
          type: string
          description: Distribution display name.
        title:
          type: string
        description:
          type: string
        web_link:
          type: string
          format: uri
        self_link:
          type: string
          format: uri

    SourcePackage:
      type: object
      properties:
        name:
          type: string
          description: Source package name.
        title:
          type: string
          description: Package title.
        web_link:
          type: string
          format: uri
        self_link:
          type: string
          format: uri