JIRA integration using Atlassian MCP Server

incident-management-api-openapi.yaml

openapi: 3.0.0
info:
  title: Incident Management API
  version: 1.0.0
  description: |
    API for managing organizational incidents including failures, critical events, and security events.
    
    ## Rate Limiting
    - 200 requests per minute per client
    - Rate limit headers included in responses
    
    ## Performance
    - P95 response time: < 200ms
  contact:
    name: API Support
    email: [email protected]

servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server

security:
  - ApiKeyAuth: []
  - OAuth2: [read, write]

paths:
  /incidents:
    post:
      summary: Create new incident
      description: Creates a new incident record in the system
      operationId: createIncident
      tags:
        - Incidents
      security:
        - ApiKeyAuth: []
        - OAuth2: [write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - severity
                - occurredAt
              properties:
                title:
                  type: string
                  description: Brief title of the incident
                  minLength: 1
                  maxLength: 200
                  example: "Database connection timeout in production"
                description:
                  type: string
                  description: Detailed description of the incident
                  maxLength: 5000
                  example: "Multiple users reported timeout errors when accessing the dashboard. Database connection pool exhausted."
                severity:
                  type: string
                  enum: [critical, high, medium, low]
                  description: Severity level of the incident
                  example: "high"
                occurredAt:
                  type: string
                  format: date-time
                  description: Timestamp when the incident occurred
                  example: "2024-01-15T14:30:00Z"
                service:
                  type: string
                  description: Service or component affected
                  maxLength: 100
                  example: "user-service"
                tags:
                  type: array
                  description: Tags for categorization
                  items:
                    type: string
                  example: ["database", "timeout", "production"]
                status:
                  type: string
                  enum: [open, investigating, resolved, closed]
                  description: Current status of the incident
                  default: open
                  example: "open"
      responses:
        '201':
          description: Incident created successfully
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per minute
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests in current window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
              example:
                id: "inc_1a2b3c4d5e6f"
                title: "Database connection timeout in production"
                description: "Multiple users reported timeout errors when accessing the dashboard. Database connection pool exhausted."
                severity: "high"
                status: "open"
                service: "user-service"
                tags: ["database", "timeout", "production"]
                occurredAt: "2024-01-15T14:30:00Z"
                resolvedAt: null
                createdAt: "2024-01-15T14:35:00Z"
                updatedAt: "2024-01-15T14:35:00Z"
                createdBy: "user_123"
                updatedBy: "user_123"
                isDeleted: false
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "ValidationError"
                message: "Invalid request body"
                details:
                  - field: "severity"
                    message: "severity must be one of: critical, high, medium, low"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "Unauthorized"
                message: "Invalid or missing API key"
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "RateLimitExceeded"
                message: "Rate limit of 200 requests per minute exceeded"

    get:
      summary: Search and list incidents
      description: Retrieve a paginated list of incidents with optional filtering and sorting
      operationId: listIncidents
      tags:
        - Incidents
      security:
        - ApiKeyAuth: []
        - OAuth2: [read]
      parameters:
        - name: status
          in: query
          description: Filter by incident status
          schema:
            type: string
            enum: [open, investigating, resolved, closed]
          example: "open"
        - name: severity
          in: query
          description: Filter by severity level
          schema:
            type: string
            enum: [critical, high, medium, low]
          example: "high"
        - name: service
          in: query
          description: Filter by service name
          schema:
            type: string
          example: "user-service"
        - name: keyword
          in: query
          description: Search keyword in title and description
          schema:
            type: string
          example: "database"
        - name: fromOccurredAt
          in: query
          description: Filter incidents that occurred after this timestamp
          schema:
            type: string
            format: date-time
          example: "2024-01-01T00:00:00Z"
        - name: toOccurredAt
          in: query
          description: Filter incidents that occurred before this timestamp
          schema:
            type: string
            format: date-time
          example: "2024-01-31T23:59:59Z"
        - name: limit
          in: query
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          example: 20
        - name: offset
          in: query
          description: Number of results to skip for pagination
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
        - name: sort
          in: query
          description: Sort order (field:direction)
          schema:
            type: string
            default: "occurredAt:desc"
          example: "occurredAt:desc"
      responses:
        '200':
          description: List of incidents retrieved successfully
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per minute
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests in current window
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Incident'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                  - id: "inc_1a2b3c4d5e6f"
                    title: "Database connection timeout in production"
                    description: "Multiple users reported timeout errors"
                    severity: "high"
                    status: "investigating"
                    service: "user-service"
                    tags: ["database", "timeout", "production"]
                    occurredAt: "2024-01-15T14:30:00Z"
                    resolvedAt: null
                    createdAt: "2024-01-15T14:35:00Z"
                    updatedAt: "2024-01-15T15:00:00Z"
                    createdBy: "user_123"
                    updatedBy: "user_456"
                    isDeleted: false
                  - id: "inc_2b3c4d5e6f7g"
                    title: "API gateway returning 503 errors"
                    description: "Gateway health check failing"
                    severity: "critical"
                    status: "open"
                    service: "api-gateway"
                    tags: ["gateway", "503", "production"]
                    occurredAt: "2024-01-15T13:00:00Z"
                    resolvedAt: null
                    createdAt: "2024-01-15T13:05:00Z"
                    updatedAt: "2024-01-15T13:05:00Z"
                    createdBy: "user_789"
                    updatedBy: "user_789"
                    isDeleted: false
                pagination:
                  totalCount: 45
                  limit: 20
                  offset: 0
                  hasMore: true
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "ValidationError"
                message: "Invalid query parameters"
                details:
                  - field: "limit"
                    message: "limit must be between 1 and 100"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /incidents/{id}:
    get:
      summary: Get incident details
      description: Retrieve detailed information about a specific incident
      operationId: getIncident
      tags:
        - Incidents
      security:
        - ApiKeyAuth: []
        - OAuth2: [read]
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the incident
          schema:
            type: string
          example: "inc_1a2b3c4d5e6f"
      responses:
        '200':
          description: Incident details retrieved successfully
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per minute
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests in current window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
              example:
                id: "inc_1a2b3c4d5e6f"
                title: "Database connection timeout in production"
                description: "Multiple users reported timeout errors when accessing the dashboard. Database connection pool exhausted."
                severity: "high"
                status: "resolved"
                service: "user-service"
                tags: ["database", "timeout", "production"]
                occurredAt: "2024-01-15T14:30:00Z"
                resolvedAt: "2024-01-15T16:45:00Z"
                createdAt: "2024-01-15T14:35:00Z"
                updatedAt: "2024-01-15T16:45:00Z"
                createdBy: "user_123"
                updatedBy: "user_456"
                isDeleted: false
        '404':
          description: Incident not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "NotFound"
                message: "Incident with id 'inc_1a2b3c4d5e6f' not found"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    patch:
      summary: Update incident
      description: Partially update an existing incident
      operationId: updateIncident
      tags:
        - Incidents
      security:
        - ApiKeyAuth: []
        - OAuth2: [write]
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the incident
          schema:
            type: string
          example: "inc_1a2b3c4d5e6f"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 200
                description:
                  type: string
                  maxLength: 5000
                severity:
                  type: string
                  enum: [critical, high, medium, low]
                status:
                  type: string
                  enum: [open, investigating, resolved, closed]
                service:
                  type: string
                  maxLength: 100
                tags:
                  type: array
                  items:
                    type: string
                occurredAt:
                  type: string
                  format: date-time
                resolvedAt:
                  type: string
                  format: date-time
                  nullable: true
            example:
              status: "resolved"
              resolvedAt: "2024-01-15T16:45:00Z"
              description: "Issue resolved by increasing database connection pool size from 50 to 100."
      responses:
        '200':
          description: Incident updated successfully
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per minute
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests in current window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
              example:
                id: "inc_1a2b3c4d5e6f"
                title: "Database connection timeout in production"
                description: "Issue resolved by increasing database connection pool size from 50 to 100."
                severity: "high"
                status: "resolved"
                service: "user-service"
                tags: ["database", "timeout", "production"]
                occurredAt: "2024-01-15T14:30:00Z"
                resolvedAt: "2024-01-15T16:45:00Z"
                createdAt: "2024-01-15T14:35:00Z"
                updatedAt: "2024-01-15T16:45:00Z"
                createdBy: "user_123"
                updatedBy: "user_456"
                isDeleted: false
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "ValidationError"
                message: "Invalid request body"
                details:
                  - field: "status"
                    message: "status must be one of: open, investigating, resolved, closed"
        '404':
          description: Incident not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "NotFound"
                message: "Incident with id 'inc_1a2b3c4d5e6f' not found"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      summary: Delete incident
      description: Perform a logical delete of an incident (sets isDeleted flag)
      operationId: deleteIncident
      tags:
        - Incidents
      security:
        - ApiKeyAuth: []
        - OAuth2: [write]
      parameters:
        - name: id
          in: path
          required: true
          description: Unique identifier of the incident
          schema:
            type: string
          example: "inc_1a2b3c4d5e6f"
      responses:
        '204':
          description: Incident deleted successfully
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Request limit per minute
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests in current window
        '404':
          description: Incident not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: "NotFound"
                message: "Incident with id 'inc_1a2b3c4d5e6f' not found"
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/oauth/authorize
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            read: Read access to incidents
            write: Write access to incidents

  schemas:
    Incident:
      type: object
      required:
        - id
        - title
        - severity
        - status
        - occurredAt
        - createdAt
        - updatedAt
        - createdBy
        - updatedBy
        - isDeleted
      properties:
        id:
          type: string
          description: Unique identifier for the incident
          example: "inc_1a2b3c4d5e6f"
        title:
          type: string
          description: Brief title of the incident
          minLength: 1
          maxLength: 200
          example: "Database connection timeout in production"
        description:
          type: string
          description: Detailed description of the incident
          maxLength: 5000
          nullable: true
          example: "Multiple users reported timeout errors when accessing the dashboard."
        severity:
          type: string
          enum: [critical, high, medium, low]
          description: Severity level of the incident
          example: "high"
        status:
          type: string
          enum: [open, investigating, resolved, closed]
          description: Current status of the incident
          example: "open"
        service:
          type: string
          description: Service or component affected
          maxLength: 100
          nullable: true
          example: "user-service"
        tags:
          type: array
          description: Tags for categorization
          items:
            type: string
          example: ["database", "timeout", "production"]
        occurredAt:
          type: string
          format: date-time
          description: Timestamp when the incident occurred
          example: "2024-01-15T14:30:00Z"
        resolvedAt:
          type: string
          format: date-time
          description: Timestamp when the incident was resolved
          nullable: true
          example: "2024-01-15T16:45:00Z"
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the incident record was created
          example: "2024-01-15T14:35:00Z"
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the incident record was last updated
          example: "2024-01-15T16:45:00Z"
        createdBy:
          type: string
          description: User ID who created the incident record
          example: "user_123"
        updatedBy:
          type: string
          description: User ID who last updated the incident record
          example: "user_456"
        isDeleted:
          type: boolean
          description: Flag indicating if the incident is logically deleted
          default: false
          example: false

    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error type or code
          example: "ValidationError"
        message:
          type: string
          description: Human-readable error message
          example: "Invalid request body"
        details:
          type: array
          description: Additional error details
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error
              message:
                type: string
                description: Specific error message for the field
          example:
            - field: "severity"
              message: "severity must be one of: critical, high, medium, low"

    Pagination:
      type: object
      required:
        - totalCount
        - limit
        - offset
        - hasMore
      properties:
        totalCount:
          type: integer
          description: Total number of items matching the query
          example: 45
        limit:
          type: integer
          description: Maximum number of items returned
          example: 20
        offset:
          type: integer
          description: Number of items skipped
          example: 0
        hasMore:
          type: boolean
          description: Indicates if there are more items available
          example: true

tags:
  - name: Incidents
    description: Operations for managing incidents

product-requirements-doc.md

Product Requirements Document (PRD) — インシデント管理API

1. 目的 / Purpose

組織内で発生するインシデント（障害・重大事象・セキュリティイベント等）の記録・更新・検索を標準化し、

チーム横断で共有できる API を提供する。

API ファーストアプローチに基づき、アプリケーション・ダッシュボード・AI エージェントが統一的にインシデント情報へアクセスできるようにする。

2. 背景 / Background

現在、インシデント情報は Excel、チャットログ、個別のツールに散在しており、情報共有が分断され、検索性・履歴の一貫性・アラート連携が不十分。

API として標準化することで以下を実現する：

• インシデント情報の一元管理
• 運用チーム・SRE・サポートチーム・AIエージェント間の連携強化
• データの検索性および可視化の改善
• 将来的な自動化（通知、レポート生成など）

3. 対象ユーザー / Target Users

• SRE / 運用チーム
• セキュリティチーム
• カスタマーサポート
• 経営層／レポーティングツール
• 外部アプリケーション（ステータスページ等）
• AIエージェント（インシデント調査や要約）

4. スコープ（In Scope）

インシデントの CRUD

• 作成（Create）
• 取得（Read）
• 更新（Update）
• 削除（Delete：論理削除を想定）

インシデントの検索 API

• ステータス検索（open / investigating / resolved / closed）
• 期間検索（発生日時・解決日時）
• 重大度検索（critical / high / medium / low）
• キーワード検索（title・description）

メタデータ管理

• 作成者／更新者
• タグ
• 関連サービス名
• タイムスタンプ

OpenAPI 仕様による定義（Spec Hub管理）

スコープ外（Out of Scope）

• アラート通知（別の Notification API で扱う想定）
• インシデントテンプレート生成
• ポストモーテム生成機能

5. 機能要件 / Functional Requirements

5.1 インシデント作成（POST /incidents）

入力例：

• title（必須）
• description（任意）
• severity（必須：critical / high / medium / low）
• status（初期値：open）
• service（任意）
• tags（任意）
• occurredAt（必須）

要件：

• 201 Created
• ID を返却
• 入力バリデーションエラー時 400

5.2 インシデント取得（GET /incidents/{id}）

• インシデント詳細情報を返す
• 存在しない ID は 404

5.3 インシデント更新（PATCH /incidents/{id}）

• 任意項目のみ更新可能
• ステータス変更履歴は自動記録（拡張要件）

5.4 インシデント削除（DELETE /incidents/{id}）

• デフォルトは論理削除（isDeleted = true）
• 204 No Content

5.5 インシデント検索（GET /incidents）

クエリパラメータ：

• status
• severity
• service
• keyword（title/description 部分一致）
• fromOccurredAt / toOccurredAt
• limit / offset
• sort（occurredAt desc がデフォルト）

要件：

• ページネーション
• × N+1 を避けるため、必要なメタデータをまとめて返す
• レスポンスはリストと totalCount を含む

6. 非機能要件 / Non-Functional Requirements

6.1 Performance

• P95 < 200ms
• 検索 API は結果件数 10,000 程度でも操作可能

6.2 Availability

• SLA 99.9%
• 障害時のステータスページ連携を考慮

6.3 Security

• API Key または OAuth2
• RBAC（閲覧と編集を分ける）
• OWASP API Security Top 10 に準拠した設計
• Rate limit: 200 req/min per client
• インシデント情報は個人情報を含む可能性があるため暗号化を推奨

6.4 Observability

• 監査ログ（誰が何を更新したか）
• Postman Insights によるエラー率・遅延監視
• Trace（サービス間フローが追えること）

7. 依存関係 / Dependencies

• データベース：PostgreSQL or DynamoDB
• API Gateway
• 認証サービス（Auth API）
• Postman Spec Hub（仕様管理）
• Postman Mock Server（早期 API テスト）
• CI/CD（GitHub Actions）

8. 成功指標（KPI） / Success Metrics

• インシデント登録までの時間 30% 短縮
• 重複インシデントの削減
• エンジニア・SRE からの検索利用率
• ダッシュボード連携数増加
• Postman Insights 上の API エラー率 < 1%

9. リスク / Risks

• スキーマが組織ごとに異なりがち（標準化の難しさ）
• 個人情報を伴うケース → セキュリティ要件強化が必要
• 高負荷時の検索性能劣化
• 認証方式変更の移行コスト

10. APIライフサイクル / Lifecycle

• Spec Hub での設計 → レビュー → 承認
• Mock Server による UI 開発者との結合前テスト
• Agent Mode を使ったテストスクリプト生成（OWASP対応）
• Insights による観測（o11y）
• バージョン管理（/v1 → /v2）

今後の追加

必要に応じて下記の要件を追加していく

• OpenAPI 3.0 仕様
• エンドポイントごとの例（example / examples）
• ER 図 / データモデル
• 状態遷移図（インシデントライフサイクル）