# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Showpad Comments API
  version: 1.0.0
extends: openapi/showpad-comments-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/comments.json'].get
  update:
    x-apievangelist-phrasing:
      intent: List comments
      effect: read
      questions:
      - Which comments have been left across our Showpad content?
      - Can I list only comments from unregistered users or created after a date?
      instructions:
      - text: List all comments.
      - text: List comments created since {createdSince}.
        slots:
          createdSince: query.createdSince
      - text: Find comments with external ID {externalId}.
        slots:
          externalId: query.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a comment
      effect: write
      questions:
      - How do I create a standalone comment?
      - Can I record a comment on behalf of an unregistered user?
      instructions:
      - text: Create a comment saying {message}.
        slots:
          message: requestBody.message
      - text: Create comment {message} from unregistered user {unregisteredUserFirstName} {unregisteredUserLastName}.
        slots:
          message: requestBody.message
          unregisteredUserFirstName: requestBody.unregisteredUserFirstName
          unregisteredUserLastName: requestBody.unregisteredUserLastName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/count.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Count comments
      effect: read
      questions:
      - How many comments exist in total?
      - What's the number of comments since a given date?
      instructions:
      - text: Count all comments.
      - text: Count comments created since {createdSince}.
        slots:
          createdSince: query.createdSince
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/description.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Describe the comment data model
      effect: read
      questions:
      - What fields does a comment object have?
      - Where can I see the API calls supported for comments?
      instructions:
      - text: Describe the comment model and its available API calls.
      - text: Show me the property definitions for the comment resource.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/{id}.json'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a comment
      effect: read
      questions:
      - How do I fetch a single comment by ID?
      - What does one comment record contain?
      instructions:
      - text: Get comment {id}.
        slots:
          id: path.id
      - text: Show the text of comment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/{id}.json'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment (PUT)
      effect: write
      questions:
      - How do I edit a comment's text with a PUT request?
      - Can I fix the author name on an unregistered user's comment with PUT?
      instructions:
      - text: PUT new text {message} on comment {id}.
        slots:
          id: path.id
          message: requestBody.message
      - text: Using PUT, set comment {id}'s unregistered last name to {unregisteredUserLastName}.
        slots:
          id: path.id
          unregisteredUserLastName: requestBody.unregisteredUserLastName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/{id}.json'].post
  update:
    x-apievangelist-phrasing:
      intent: Edit a comment (POST)
      effect: write
      questions:
      - Can I update a comment with POST instead of PUT?
      - Is there a POST variant for changing a comment's external ID?
      instructions:
      - text: Via POST, change comment {id}'s message to {message}.
        slots:
          id: path.id
          message: requestBody.message
      - text: Using the POST update, set external ID {externalId} on comment {id}.
        slots:
          id: path.id
          externalId: requestBody.externalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/comments/{id}.json'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a comment
      effect: destructive
      questions:
      - How do I delete a comment?
      - Can I remove an inappropriate comment permanently?
      instructions:
      - text: Delete comment {id}.
        slots:
          id: path.id
      - text: Remove comment {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'