v3spec.yml

openapi: 3.0.3

info:
  version: '3.0'
  title: 'V3'
  description: |
    Request Timing
    When methods on the SDK are called, it should generally enqueue data locally into offline storage, and make batched flushes to the above endpoints on a timed basis, or when explicitly requested by the user. In general, the default flush interval should be in the 10s of seconds (reasonable default may depend on the nature of the platform), and should be configurable.

    In the case of request failure (any non-20x response), the SDK should re-enqueue any failed events or attributes into local offline storage, and should begin an exponential slowdown of the flush interval, until a successful response is received. The backoff function should follow the decorrelated jitter algorithm below:
    ```
    sleep = min(5_minutes, random_between(normal_flush_interval, previous_sleep_time * 3))
    ```
    App Version Code
    See App Version Filter Functionality Improvement for the original design document. This field is the machine-parsable equivalent to `app_version`. This value incorporates the basic principles from https://semver.org/ but is extended for our needs to a fourth field, REVISION. Thus, this value is to be interpreted as `MAJOR.MINOR.PATCH.REVISION`. Missing values for any of the four aforementioned fields should be interpreted as 0. For example, "11.20.3" would correlate to MAJOR-11 MINOR-20 PATCH-3 REVISION-0.

    HTTP Headers
    All HTTP calls should include the following HTTP Header:

    `X-Braze-Api-Key:API` key for the app

    Based on the respond_with object, additional HTTP Headers should be added to the request. This allows DevOps to load balance the API calls based on what they are requesting.

    If respond_with contains more than just config, such as including feed or triggers, include the following HTTP header:

    `X-Braze-DataRequest:true`

    If respond_with includes feed, also include the following HTTP header:

    `X-Braze-FeedRequest:true`

    If respond_with includes triggers, also include the following HTTP header:

    `X-Braze-TriggersRequest:true`



  contact:
    name: PlatformName
    email: platform@braze.com

servers:
  - url: http://localhost:{port}/api/v3
    description: Local dev server
    variables:
      port:
        default: 8080

  - url: https://sondheim.appboy.com/api/v3/data
    description: Staging server

  - url: https://dev.appboy.com/api/v3/data
    description: Production server

paths:
  /:
    post:
      parameters:
      - in: header
        name: X-Braze-Api-Key
        description: API key for the app
        type: string
        required: true
      - in: header
        name: X-Braze-DataRequest
        description: Include if respond_with contains more than just config, such as including feed or triggers
        type: string
      - in: header
        name: X-Braze-FeedRequest
        description: Include if respond_with includes feed
        type: string
      - in: header
        name: X-Braze-TriggersRequest
        description: Include if respond_with includes triggers
        type: string

      summary: test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Root'
        required: true
      # headers:
      #     X-Rate-Limit:
      #       description: calls per hour allowed by the user
      #       schema:
      #         type: integer
      #         format: int32
      #     X-Expires-After:
      #       description: date in UTC when token expires
      #       schema:
      #         type: string
      #         format: date-time

components:
  schemas:
    Root:
      type: "object"
      properties:
        api_key:
          description: API key for requesting App
          type: "string"
          required: true
        device_id:
          description: device identifier for requester
          type: "string"
          required: true
        time:
          description: UNIX timestamp of request initiation
          type: "integer"
          required: true
        sdk_version:
          description: |
            Braze SDK version. Must conform to regex: `/\A(\d+\.?){1,4}\z/`
          type: "string"
          required: true

        app_version_code:
          description: |
            The machine-readable build version of the host app. Must consist solely of 4 numbers and periods in accordance with the regex `/\A(\d+\.){3}(\d+)\z/` e.g. 1.2.3.4.

            See App Version Filter Functionality Improvement for the original design document. This field is the machine-parsable equivalent to `app_version`. This value incorporates the basic principles from https://semver.org/ but is extended for our needs to a fourth field, REVISION. Thus, this value is to be interpreted as `MAJOR.MINOR.PATCH.REVISION`. Missing values for any of the four aforementioned fields should be interpreted as 0. For example, "11.20.3" would correlate to MAJOR-11 MINOR-20 PATCH-3 REVISION-0.
          type: "string"
        app_version:
          description: version of the host app
          type: "string"
        device:
          description: information about the device
          type: "object"
        events:
          description: events to record for their respective users
          type: "array"
          items:
            type: "string"
        attributes:
          description: attributes to set for their respective users
          type: "array"
          items:
            type: "string"
        feedback:
          description: feedback items to submit. (Deprecated)
          type: "array"
          items:
            type: "string"
        respond_with:
          description: data requested in response
          type: "object"
        sdk_flavor:
          description: The type of SDK making the request. Note that "wordpress" is web only
          type: "string"
          enum:
          - "unity"
          - "react"
          - "cordova"
          - "xamarin"
          - "segment"
          - "mparticle"
          - "flutter"
          - "wordpress"
          - "amp"
          - "tealium"
        test_user_data:
          description: Test user data objects, such as device logs. Expects only 1 TestUserDataObject per user-id
          type: "array"
          items:
            type: "string"