openapi: 3.0.0
info:
  description: >
    This document specifies an **Registration Composer RESTful API** for **WSO2
    Identity Server**.
  version: '1.0'
  title: WSO2 Identity Server - Registration Flow Management Rest API
  termsOfService: 'http://swagger.io/terms/'
  contact:
    name: WSO2
    url: 'http://wso2.com/identity-server/'
    email: architecture@wso2.org
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'

security:
  - OAuth2: []
  - BasicAuth: []

servers:
  - url: 'https://{server-url}/t/{tenant-domain}/api/server/v1'
    variables:
      tenant-domain:
        default: "carbon.super"
      server-url:
        default: "localhost:9443"
paths:
  /registration-flow/:
    get:
      summary: Retrieve the complete registration flow
      operationId: getRegistrationFlow
      tags:
        - Registration Flow
      responses:
        200:
          description: Successfully retrieved the registration flow
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegistrationFlowResponse"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: Update the complete registration flow
      operationId: updateRegistrationFlow
      tags:
        - Registration Flow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegistrationFlowRequest"
      responses:
        200:
          description: Registration flow successfully updated
        400:
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        401:
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        403:
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        500:
          description: Encountered a server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    RegistrationFlowRequest:
      type: object
      description: Request payload for creating or updating a registration flow
      properties:
        steps:
          type: array
          items:
            $ref: "#/components/schemas/Step"

    RegistrationFlowResponse:
      type: object
      description: Response payload for retrieving a registration flow
      properties:
        steps:
          type: array
          items:
            $ref: "#/components/schemas/Step"

    Step:
      type: object
      description: Represent a single step in the registration flow process
      required:
        - id
        - type
        - data
        - size
        - position
      properties:
        id:
          type: string
          description: Unique identifier of the step
          example: dnd-step-3fa85f64-5717-4562-b3fc-2c963f66afa6
        type:
          type: string
          description: Type of the step
          example: VIEW
        data:
          $ref: "#/components/schemas/Data"
        size:
          $ref: "#/components/schemas/Size"
        position:
          $ref: "#/components/schemas/Position"
    Data:
      type: object
      properties:
        components:
          type: array
          items:
            $ref: "#/components/schemas/Component"
        action:
          $ref: "#/components/schemas/Action"
    Component:
      type: object
      description: Represent individual UI components in the registration flow
      required:
        - id
        - category
        - type
      properties:
        id:
          type: string
          description: Unique identifier of the component
          example: dnd-component-210e95c0-c580-40b0-9646-7054bb340f64
        category:
          type: string
          description: Type of component
          example: FIELD
        type:
          type: string
          description: Specific component type (e.g., INPUT, BUTTON)
          example: INPUT
        variant:
          type: string
          description: Variant of the component (e.g., PRIMARY, TEXT)
          example: PASSWORD
        version:
          type: string
          description: Version of the component
          example: "1.0.0"
        deprecated:
          type: boolean
          description: Indicate whether the component is deprecated
          example: false
        components:
          type: array
          items:
            $ref: "#/components/schemas/Component"
        action:
          $ref: "#/components/schemas/Action"
        config:
          type: object
          description: Configuration details of the component

    Action:
      type: object
      description: Represent an action which controls the registration flow
      required:
        - type
        - next
      properties:
        type:
          type: string
          description: Type of action
          example: EXECUTOR
        executor:
          $ref: "#/components/schemas/Executor"
        next:
          type: string
          description: ID of the next step. For the last step, value will be "COMPLETE"
          example: dnd-step-asd85f64-5717-4562-b3fc-2234f66afa6

    Executor:
      type: object
      description: Represent the execution that an action is going to perform
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the executor
          example: GoogleSignUpExecutor
        meta:
          type: object
          description: Contains metadata related to the executor
          example:
            {
              "idp": "google1"
            }

    Size:
      type: object
      description: Represent the dimensions of a step
      required:
        - height
        - width
      properties:
        height:
          type: number
          example: 200
        width:
          type: number
          example: 160

    Position:
      type: object
      description: Represent the coordinates of a step in the composer canvas
      required:
        - x
        - y
      properties:
        x:
          type: number
          example: 120.12
        y:
          type: number
          example: 200.22

    Error:
      type: object
      properties:
        code:
          type: string
          example: AAA-00000
        message:
          type: string
          example: Some Error Message
        description:
          type: string
          example: Some Error Description
        traceId:
          type: string
          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://localhost:9443/oauth2/authorize'
          tokenUrl: 'http://localhost:9443/oauth2/token'
          scopes: {}
