spec.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: push-notifications
  description: A service for sending push notification messages
  termsOfService: https://wikimediafoundation.org/wiki/Terms_of_Use
  contact:
    name: the Wikimedia Product Infrastructure team
    url: https://www.mediawiki.org/wiki/Wikimedia_Product_Infrastructure_team/Push_Notifications_Infrastructure
  license:
    name: Apache2
    url: http://www.apache.org/licenses/LICENSE-2.0
x-default-params:
  domain: en.wikipedia.org

paths:
  # from routes/root.ts
  /robots.txt:
    get:
      tags:
        - Admin
      description: Gets robots.txt
      responses:
        200:
          description: Success
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
      x-amples:
        - title: robots.txt check
          request: {}
          response:
            status: 200
  /:
    get:
      tags:
        - Admin
      description: The root service end-point
      responses:
        200:
          description: Success
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
      x-amples:
        - title: root with no query params
          request: {}
          response:
            status: 404
        - title: spec from root
          request:
            query:
              spec: true
          response:
            status: 200
        - title: doc from root
          request:
            query:
              doc: true
          response:
            status: 200
        - title: root with wrong query param
          request:
            query:
              fooo: true
          response:
            status: 404

  # from routes/info.ts
  /_info:
    get:
      tags:
        - Admin
      description: Gets information about the service
      responses:
        200:
          description: OK
      x-amples:
        - title: retrieve service info
          request: {}
          response:
            status: 200
            headers:
              content-type: application/json
            body:
              name: /.+/
              description: /.+/
              version: /.+/
              home: /.+/
  /_info/name:
    get:
      tags:
        - Admin
      description: Gets the name of the service
      responses:
        200:
          description: OK
      x-amples:
        - title: retrieve service name
          request: {}
          response:
            status: 200
            headers:
              content-type: application/json
            body:
              name: /.+/
  /_info/version:
    get:
      tags:
        - Admin
      description: Gets the running version of the service
      responses:
        200:
          description: OK
      x-amples:
        - title: retrieve service version
          request: {}
          response:
            status: 200
            headers:
              content-type: application/json
            body:
              version: /.+/
  /_info/home:
    get:
      tags:
        - Admin
      description: Redirects to the home page
      responses:
        301:
          description: Redirect
      x-amples:
        - title: redirect to the home page
          request: {}
          response:
            status: 301

  # from routes/v1.ts
  /v1/message/fcm:
    post:
      tags:
      - Push notifications
      summary: Send a push notification to one or more devices via FCM
      description: Sends a push notification request to Firebase Cloud Messaging.
      requestBody:
        content:
          application/json:
            schema:
              required:
              - deviceTokens
              - messageType
              properties:
                deviceTokens:
                  type: array
                  description: FCM device tokens identifying the device(s) to which to send the message.
                  example: [ __REPLACE_ME__ ]
                messageType:
                  type: string
                  description: The type of message to send to the push vendor.
                  enum:
                  - checkEchoV1
                dryRun:
                  type: boolean
                  description: Set this property to true if the message should not reach the target device.
                  example: false
        required: true
      x-amples:
        - title: FCM message (dry-run)
          request:
            body:
              deviceTokens: ['x-ample-fcm']
              messageType: 'checkEchoV1'
              dryRun: true
          response:
            status: 200
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        504:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'

  /v1/message/apns:
    post:
      tags:
      - Push notifications
      summary: Send a push notification to APNS
      description: Sends a push notification request to Apple Push Notification Service.
      requestBody:
        content:
          application/json:
            schema:
              required:
              - deviceToken
              - messageType
              properties:
                deviceTokens:
                  type: array
                  description: APNS device tokens identifying the device(s) to which to send the message.
                  example: [__REPLACE_ME__]
                messageType:
                  type: string
                  description: The type of message to send to the push vendor.
                  enum:
                  - checkEchoV1
                topic:
                  type: string
                  description: The APNS topic (app bundle ID) to send the notification to.
                dryRun:
                  type: boolean
                  description: Set this property to true if the message should not reach the target device.
                  example: false
        required: true
      x-amples:
        - title: APNS message (dry-run)
          request:
            body:
              deviceTokens: ['x-ample-apns']
              messageType: 'checkEchoV1'
              dryRun: true
          response:
            status: 200
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
        404:
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        504:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'

components:
  schemas:
    success:
      properties:
        {}

    # A https://tools.ietf.org/html/draft-nottingham-http-problem
    problem:
      required:
        - type
      properties:
        status:
          type: integer
        type:
          type: string
        title:
          type: string
        detail:
          type: string
        method:
          type: string
        uri:
          type: string