bucketing-api.yaml

openapi: 3.1.0
info:
  title: DevCycle Bucketing API
  description:
    Documents the DevCycle Bucketing API (https://bucketing-api.devcycle.com/) which provides an API interface to
    User Bucketing and for generated SDKs.

servers:
  - url: https://bucketing-api.devcycle.com/

tags:
  - name: EdgeDB
  - name: Bucketing API
  - name: Feature Opt-in
  - name: OpenFeature Remote Evaluation API (OFREP)
    description:
      "See the OpenFeature documentation for more information: https://github.com/open-feature/protocol"

paths:
  /v1/variables/{key}:
    post:
      summary: Get variable by key for user data
      tags:
        - Bucketing API
      operationId: 'getVariableByKey'
      security:
        - bearerAuth: []
      parameters:
        - name: key
          in: path
          description: Variable key
          required: true
          schema:
            type: string

      requestBody:
        $ref: '#/components/requestBodies/UserRequestBody'

      responses:
        200:
          description: Variable response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Variable'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'

  /v1/variables:
    post:
      summary: Get all variables by key for user data
      tags:
        - Bucketing API
      security:
        - bearerAuth: []
      operationId: 'getVariables'
      requestBody:
        $ref: '#/components/requestBodies/UserRequestBody'
      responses:
        200:
          description: Variables response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Variable'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'

  /v1/features:
    post:
      summary: Get all features by key for user data
      tags:
        - Bucketing API
      operationId: 'getFeatures'
      security:
        - bearerAuth: []
      requestBody:
        $ref: '#/components/requestBodies/UserRequestBody'
      responses:
        200:
          description: Feature response
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Feature'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'

  /v1/track:
    post:
      summary: Post events to DevCycle for user
      tags:
        - Bucketing API
      security:
        - bearerAuth: []
      operationId: 'postEvents'
      requestBody:
        $ref: '#/components/requestBodies/TrackRequestBody'
      responses:
        201:
          description: Feature response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'

  /v1/edgedb/{id}:
    patch:
      summary: Update EdgeDB data based on unique id and project id
      tags:
        - EdgeDB
      parameters:
        - in: path
          name: id
          schema:
            type: string
          required: true
          description: A unique id used to fetch and update the EdgeDB data
        - name: sdkKey
          in: query
          description: SDK Key as defined in the dashboard for your DevCycle environment.
            One of the Authorization header or "sdkKey" query parameter is required to be set.
          required: false
          schema:
            type: string

      requestBody:
        description: User properties to update the EdgeDB data
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDataEdgeDB'

      responses:
        200:
          description: Client SDK API Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EdgeDBApiResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        404:
          $ref: '#/components/responses/NotFound'
        500:
          $ref: '#/components/responses/InternalServerError'

  /v1/optInConfig:
    get:
      summary: Fetch opt-in config
      description: Fetch a project config to display features available for Opt-in
      tags:
        - Feature Opt-in
      parameters:
        - name: sdkKey
          in: query
          description: SDK Key as defined in the dashboard for your DevCycle environment.
            One of the Authorization header or "sdkKey" query parameter is required to be set.
          required: false
          schema:
            type: string
        - name: user_id
          in: query
          description: Unique id to identify the user
          required: true
          schema:
            type: string
      responses:
        200:
          description: Opt-in Config Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptInConfigResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        500:
          $ref: '#/components/responses/InternalServerError'

  /v1/optIns/:user_id:
    put:
      summary: Update opt-in preferences for a user
      tags:
        - Feature Opt-in
      parameters:
        - name: sdkKey
          in: query
          description: SDK Key as defined in the dashboard for your DevCycle environment.
            One of the Authorization header or "sdkKey" query parameter is required to be set.
          required: false
          schema:
            type: string
      requestBody:
        description: A map of feature IDs to boolean values. The value should be true if the user has opted in, false otherwise
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserOptInData'
      responses:
        200:
          description: Opt-in Config Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptInConfigResponse'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/UnauthorizedError'
        500:
          $ref: '#/components/responses/InternalServerError'

  /ofrep/v1/evaluate/flags/{key}:
    post:
      tags:
        - OpenFeature Remote Evaluation API (OFREP)
      summary:
        OFREP Single Flag Evaluation Request
      description:
        Return a single flag for a user context
      parameters:
        - name: key
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ofrep-evaluationRequest'
      responses:
        '200':
          description: OFREP successful evaluation response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ofrep-evaluationSuccess'
        '400':
          description: Bad evaluation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ofrep-evaluationFailure'
        '404':
          description: Flag not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ofrep-flagNotFound'
        '401':
          description: Unauthorized - You need credentials to access the API
        '403':
          description: Forbidden - You are not authorized to access the API
        '429':
          description: Rate limit reached on the Flag Management System
          headers:
            Retry-Later:
              description: Indicates when to retry the request again
              schema:
                type: string
                format: date-time
                examples:
                  - '2024-02-07T12:00:00Z'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ofrep-generalErrorResponse'

  /ofrep/v1/evaluate/flags:
    post:
      tags:
        - OpenFeature Remote Evaluation API (OFREP)
      summary:
        OFREP Bulk Evaluation Request
      description:
        Return all flag values for a user context.
      parameters:
        - in: header
          name: If-None-Match
          description: The request will be processed only if ETag doesn't match any of the values listed.
          schema:
            type: string
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ofrep-bulkEvaluationRequest'
      responses:
        '200':
          description: OFREP successful evaluation response
          headers:
            ETag:
              schema:
                type: string
              description: Entity tag used for cache validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ofrep-bulkEvaluationSuccess'
        '304':
          description: Bulk evaluation is not modified
        '400':
          description: Bad evaluation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ofrep-bulkEvaluationFailure'
        '401':
          description: Unauthorized - You need credentials to access the API
        '403':
          description: Forbidden - You are not authorized to access the API
        '429':
          description: Rate limit reached on the Flag Management System
          headers:
            Retry-Later:
              description: Indicates when to retry the request again
              schema:
                type: string
                format: date-time
                examples:
                  - '2024-02-07T12:00:00Z'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ofrep-generalErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Enter your DevCycle SDK token'

  schemas:
    UserDataEdgeDB:
      type: object
      properties:
        user_id:
          description: Unique id to identify the user
          type: string

        email:
          description: User's email used to identify the user on the dashaboard / target audiences
          type: string

        name:
          description: User's name used to idenify the user on the dashaboard / target audiences
          type: string

        language:
          description: User's language in ISO 639-1 format
          additionalProperties:
            type: string
            maxLength: 2

        country:
          description: User's country in ISO 3166 alpha-2 format
          additionalProperties:
            type: string
            maxLength: 2

        customData:
          description: User's custom data to target the user with, data will be logged to DevCycle for use in dashboard.
          type: object

        lastSeenDate:
          description: Date the user was last seen being used, Unix epoch timestamp format
          type: number

      required:
        - user_id

    UserData:
      type: object
      properties:
        user_id:
          type: string
          description: Unique id to identify the user
        email:
          type: string
          description: User's email used to identify the user on the dashboard / target audiences
        name:
          type: string
          description: User's name used to identify the user on the dashboard / target audiences
        language:
          type: string
          description: User's language in ISO 639-1 format
          maxLength: 2
        country:
          type: string
          description: User's country in ISO 3166 alpha-2 format
          maxLength: 2
        appVersion:
          type: string
          description: App Version of the running application
        appBuild:
          type: string
          description: App Build number of the running application
        customData:
          type: object
          description: User's custom data to target the user with, data will be logged to DevCycle for use in dashboard.
        privateCustomData:
          type: object
          description:
            User's custom data to target the user with, data will not be logged to DevCycle
            only used for feature bucketing.
        createdDate:
          type: number
          description: Date the user was created, Unix epoch timestamp format
        lastSeenDate:
          type: number
          description: Date the user was created, Unix epoch timestamp format
        platform:
          type: string
          description: Platform the Client SDK is running on
        platformVersion:
          type: string
          description: Version of the platform the Client SDK is running on
        deviceModel:
          type: string
          description: User's device model
        sdkType:
          type: string
          description: DevCycle SDK type
          enum: [api, server]
        sdkVersion:
          type: string
          description: DevCycle SDK Version
      required:
        - user_id

    UserDataAndEventsBody:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        user:
          $ref: '#/components/schemas/UserData'

    UserOptInData:
      type: object
      additionalProperties:
        type: boolean


    Feature:
      type: object
      properties:
        _id:
          type: string
          description: unique database id
        key:
          type: string
          description: Unique key by Project, can be used in the SDK / API to reference by 'key' rather than _id.
        type:
          type: string
          description: Feature type
          enum: [ 'release', 'experiment', 'permission', 'ops' ]
        _variation:
          type: string
          description: Bucketed feature variation ID
        variationName:
          type: string
          description: Bucketed feature variation Name
        variationKey:
          type: string
          description: Bucketed feature variation Key
        evalReason:
          type: string
          description: Evaluation reasoning
      required:
        - _id
        - key
        - type
        - _variation

    Variable:
      type: object
      properties:
        _id:
          type: string
          description: unique database id
        key:
          type: string
          description: Unique key by Project, can be used in the SDK / API to reference by 'key' rather than _id.
        type:
          type: string
          description: Variable type
          enum: [ 'String', 'Boolean', 'Number', 'JSON' ]
        value:
          type: object
          description: Variable value can be a string, number, boolean, or JSON
      required:
        - _id
        - key
        - type
        - value

    Event:
      type: object
      properties:
        type:
          type: string
          description: Custom event type
        target:
          type: string
          description: Custom event target / subject of event. Contextual to event type
        date:
          type: number
          description: Unix epoch time the event occurred according to client
        value:
          type: number
          description: Value for numerical events. Contextual to event type
        metaData:
          type: object
          description: Extra JSON metadata for event. Contextual to event type
      required:
        - type

    EdgeDBApiResponse:
      type: object
      properties:
        message:
          description: Response message of the request
          type: string
      required:
        - message

    OptInConfigResponse:
      type: object
      properties:
        message:
          description: Response message of the request
          type: string
      required:
        - message

    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: number
          description: Error response status code
        message:
          type: string
          description: Error message
        data:
          type: object
          description: Additional error information detailing the error reasoning
      required:
        - message

    # OpenFeature Remote Evaluation API Schemas
    ofrep-bulkEvaluationRequest:
      description: Evaluate multiple flags in one request
      properties:
        context:
          $ref: '#/components/schemas/ofrep-context'
    ofrep-bulkEvaluationSuccess:
      description: Success response for the bulk evaluation request
      type: object
      properties:
        flags:
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/ofrep-evaluationSuccess"
              - $ref: '#/components/schemas/ofrep-evaluationFailure'

    ofrep-bulkEvaluationFailure:
      description: Bulk evaluation failure response
      properties:
        errorCode:
          type: string
          description: An appropriate  code specific to the bulk evaluation error. See https://openfeature.dev/specification/types#error-code
        errorDetails:
          type: string
          description: Optional error details description for logging or other needs
      required:
        - errorCode

    ofrep-evaluationRequest:
      description: Flag evaluation request
      properties:
        context:
          $ref: '#/components/schemas/ofrep-context'

    ofrep-evaluationSuccess:
      description: Flag evaluation success response.
      allOf:
        - properties:
            key:
              $ref: "#/components/schemas/ofrep-key"
            reason:
              type: string
              enum: [ STATIC,TARGETING_MATCH,SPLIT,DISABLED,UNKNOWN ]
              description: An OpenFeature reason for the evaluation
            variant:
              type: string
              description: Variant of the evaluated flag value
            metadata:
              type: object
              description: Arbitrary metadata supporting flag evaluation
        - oneOf:
            - $ref: "#/components/schemas/ofrep-booleanFlag"
            - $ref: "#/components/schemas/ofrep-stringFlag"
            - $ref: "#/components/schemas/ofrep-integerFlag"
            - $ref: "#/components/schemas/ofrep-floatFlag"
            - $ref: "#/components/schemas/ofrep-objectFlag"

    ofrep-evaluationFailure:
      description: Flag evaluation failure response
      properties:
        key:
          $ref: '#/components/schemas/ofrep-key'
        errorCode:
          type: string
          enum: [ PARSE_ERROR,TARGETING_KEY_MISSING,INVALID_CONTEXT,GENERAL ]
          description: OpenFeature compatible error code. See https://openfeature.dev/specification/types#error-code
        errorDetails:
          $ref: '#/components/schemas/ofrep-errorDetails'
      required:
        - key
        - errorCode

    ofrep-flagNotFound:
      description: Flag not found response
      properties:
        key:
          $ref: '#/components/schemas/ofrep-key'
        errorCode:
          type: string
          enum: [ FLAG_NOT_FOUND ]
        errorDetails:
          $ref: '#/components/schemas/ofrep-errorDetails'
      required:
        - key
        - errorCode

    ofrep-generalErrorResponse:
      description: A general error response from the service
      properties:
        errorDetails:
          $ref: '#/components/schemas/ofrep-errorDetails'

    ofrep-key:
      type: string
      description: Feature flag key
      examples:
        - my-flag

    ofrep-context:
      type: object
      description: Context information for flag evaluation

    ofrep-booleanFlag:
      description: A boolean typed flag value
      properties:
        value:
          type: boolean
          description: Flag evaluation result
      required:
        - value

    ofrep-stringFlag:
      description: A string typed flag value
      properties:
        value:
          type: string
          description: Flag evaluation result
          examples:
            - "my-flag-value"
      required:
        - value

    ofrep-integerFlag:
      description: An integer typed flag value
      properties:
        value:
          type: integer
          description: Flag evaluation result
          examples:
            - 3
      required:
        - value

    ofrep-floatFlag:
      description: A float typed flag value
      properties:
        value:
          type: number
          description: Flag evaluation result
          examples:
            - 3.1415
      required:
        - value

    ofrep-objectFlag:
      description: An object typed flag value
      properties:
        value:
          type: object
          description: Flag evaluation result
      required:
        - value

    ofrep-errorDetails:
      type: string
      description: An error description for logging or other needs

  requestBodies:
    UserRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserData'

    TrackRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UserDataAndEventsBody'

  responses:
    # 400
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    # 401
    UnauthorizedError:
      description: Missing 'sdkKey' query parameter or 'Authorization' header
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    # 404
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

    # 500
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'