openapi: 3.1.0
info:
  title: Google Books About Watch API
  description: API for retrieving Bookshelf and Volume resources from Google Books
  version: 1.0.0
  contact:
    name: Google Books API
    url: https://developers.google.com/books
servers:
- url: https://www.googleapis.com/books/v1
  description: Google Books API v1
tags:
- name: Watch
  description: Operations related to Watch
paths:
  /gmail/v1/users/{userId}/watch:
    post:
      tags:
      - Watch
      summary: Google Watch Users
      description: The Watch Users operation in the Google Gmail API allows applications to set up push notifications for a user's mailbox by establishing a watch on their Gmail account. When called via POST to /gmail/v1/users/{userId}/watch, this endpoint configures Gmail to send notifications to a specified Cloud Pub/Sub topic whenever changes occur in the user's mailbox, such as receiving new emails, messages being deleted, or labels being modified. The watch remains active for a renewable period (default 7 days), and applications must include the target Pub/Sub topic details in the request body along with optional filters to specify which types of events should trigger notifications. This enables real-time synchronization and event-driven architectures without the need for constant polling of the mailbox.
      parameters:
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      - name: Accept
        in: header
        schema:
          type: string
        example: application/json
      - name: userId
        in: path
        schema:
          type: string
        required: true
        description: '(Required) '
        example: incididunt labore i
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GmailUsersWatchPostRequest'
      responses:
        '200':
          description: OK
          headers:
            Content-Type:
              schema:
                type: string
                example: application/json
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GmailUsersWatchPostResponse'
              examples:
                GmailUsersWatchPostResponseExample:
                  $ref: '#/components/examples/GmailUsersWatchPostResponseExample'
      x-api-evangelist-processing:
        ChooseTags: true
        WriteDescription: true
      x-microcks-operation:
        delay: 100
        dispatcher: FALLBACK
        dispatcherRules: GmailUsersWatchPostResponseExample
components:
  schemas:
    GmailUsersWatchPostResponse:
      description: GmailUsersWatchPostResponse schema
      type: object
      properties:
        historyId:
          type: string
        expiration:
          type: string
    GmailUsersWatchPostRequest:
      description: GmailUsersWatchPostRequest schema
      type: object
      example:
        labelIds:
        - officia ex reprehenderit et
        - labore ullamco ut
        labelFilterAction: exclude
        labelFilterBehavior: include
        topicName: Ut enim in in
  examples:
    GmailUsersWatchPostResponseExample:
      summary: Successful 200 response
      value:
        historyId: quis aute sed
        expiration: dolore non exercitation Excepteur est
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication for Google Books API
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/v2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/books: Manage your Google Books library