openapi: 3.0.0
info:
  title: Organizational Units API                                       # TITLE OF THE DOCUMENT (REQUIRED)
  description: 'The Organizational Units (OUs) API provides programmatic access to manage Active Directory (AD) OUs. The ADManager Plus API offers endpoints to update and retrieve OUs using structured requests with support for filtering, sorting, and pagination. OUs are used to organize users, groups, computers, and other OUs within a domain, and the API enables administrators to automate restructuring, attribute updates, and reporting with consistency across environments.'
  contact: {}
  version: 2.0.0
servers:
  -
    url: 'http://admanagerplus:8080/api/v2'                       # PRODUCT URL
    description: 'API Endpoint'                            # URL DESCRIPTION
tags:
  -
    name: api-for-ou                                   # TAG NAME SHOULD BE SAME AS DEFINED IN APP.YML TAGS & SAME AS YML FILE NAME (REQUIRED)
    description: 'Organizational units Endpoint'                      # DESCRIPTION ABOUT THE TAG NAME
security:
  - authToken: []
paths:
  /organizational_units  :
    get:
      tags:
        - api-for-ou
      summary: List AD OUs
      description: |
        This endpoint retrieves AD OUs based on specified filters, sort order, and pagination. You can also limit the response to specific fields for efficiency. It is often used for OU inventory, reporting, or preparing for administrative delegation.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/date_format'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domains'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/refresh'
      responses:
        "200":
          description: Successful response with AD OUs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_ous_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: UnAuthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      security: 
        - authToken: 
          - Read OU action, All OU management actions
          - delegated-roles
          - All OUs Report
    patch:
      tags:
        - api-for-ou 
      summary: Update AD OUs
      description: This endpoint updates existing OUs with the specified payload. You can modify attributes such as name, description, location, and administrative details. It is commonly used when restructuring domains, changing OU ownership, or updating organizational information.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/xModule'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/domain'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/refresh'
      requestBody:
        description: ""
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update_ous_body'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_ous_response'
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad_request_response'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized_response'
        "500":
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/internal_server_error_response'
      deprecated: false
      security: 
        - authToken:
          - Modify OU action, All OU management actions
          - delegated-roles
          - Modify Bulk OUs, Bulk OU Modification
components:
  parameters:
    authorization:
      name: Authorization
      in: header
      schema:
        type: string
      description: 'Authtoken for the API'
      required: true
      example: '41d**************125f'
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'The response format that the client accepts.'
      required: false
      example: 'application/json'
    contentType:
      name: Content-Type
      in: header
      schema:
        type: string
      description: 'The format of data sent to the server. This value is passed in the Content-Type header of the API request.'
      required: false
      example: 'application/json'
    xModule:
      name: X-Module
      in: header
      schema:
        type: string
      description: 'The module name to be recorded in the audit logs. If not provided, the default module is recorded as Rest API.'
      required: false
      example: 'External API'
    from:
      in: query
      name: from
      schema:
        type: integer
        minimum: 1
      description: 'The starting index for pagination. Enables pagination through large result sets.'
      required: false
      example: 1
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 100
        minimum: 1
      description: 'The maximum number of OU records to return per request.'
      required: false
      example: 50
    domains:
      in: query
      name: domains
      schema:
        type: string
      description: >
        A comma-separated list of domains from which to fetch OUs.
        <br>
        <strong>Example:</strong>  domain1.com,domain2.com
      required: true
      example: domain1.com
    fields:
      in: query
      name: fields
      schema:
        type: string
      description: 'The attributes to be returned in the response.'
      required: false
      example: 'NAME,DISTINGUISHED_NAME'
    filter:
      in: query
      name: filter
      schema:
        type: string
      description: >
        A SCIM filter query to refine which objects are returned. See <a href="https://www.manageengine.com/in/products/ad-manager/active-directory-api/v2/filters/#overview">Filter section</a> for details.
        <br>
        <strong>eg:</strong> (FULL_NAME eq Finance) and (CITY eq New York)
      required: false
      example: (FULL_NAME eq Finance) and (CITY eq New York)
    sort:
      in: query
      name: sort
      schema:
        type: string
      description: >
       This field is used to sort results. The default sort order is ascending. To sort in descending order, prefix the field with a hyphen (-).
        <br>
        <strong>eg:</strong>  FULL_NAME
      required: false
      example: '-FULL_NAME'
    refresh:
      in: query
      name: refresh
      description: If set to true, triggers a sync before fetching results, ensuring that the data reflects the latest state of AD.
      required: false
      schema:
        type: boolean
    date_format :
      name: X-Date-Time-Format
      in: header
      description: "The date-time format to be used for parsing date values returned in the response. If not provided, the default ISO format is used (yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX])."
      required: false
      schema:
        type: string
    domain:
      in: query
      name: domain
      description: >
        The AD domain where the requested operation is performed.
        <br>
        <strong>eg:</strong> domain1.com
      required: true
      schema:
        type: string
      example: domain1.com
  schemas:
    list_ous_response: 
      type: object
      properties:
        data:
          type: array
          example:
            - NAME: "OUAPI1"
              DISTINGUISHED_NAME: "OU=OUAPI1,OU=OUS,DC=domain,DC=com"
              OU_NAME: "domain.com/OUS/OUAPI1"
              CITY: "Chennai"
              COUNTRY: "India"
              STATE_PROVINCE: "-"
              OBJECT_GUID: "{715EC375-CC40-9A61-9C8E-DF9B7989D3FD}"
              MANAGER: "Manager 1"
            - NAME: "OUAPI2"
              DISTINGUISHED_NAME: "OU=OUAPI2,OU=OUS,DC=domain,DC=com"
              OU_NAME: "domain.com/OUS/OUAPI2"
              CITY: "Bangalore"
              COUNTRY: "India"
              STATE_PROVINCE: "-"
              OBJECT_GUID: "{715EC375-CC40-9A61-9C8E-DF9B7989D3FE}"
              MANAGER: "Manager 2"
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 10
            total_no_of_objects: 2

    ous_array:
      type: array
      items:
        example:
          - NAME: "OUAPI1"
            DISTINGUISHED_NAME: "OU=OUAPI1,OU=OUS,DC=domain,DC=com"
            OU_NAME: "domain.com/OUS/OUAPI1"
            CITY: "Chennai"
            COUNTRY: "India"
            STATE_PROVINCE: "-"
            OBJECT_GUID: "{715EC375-CC40-9A61-9C8E-DF9B7989D3FD}"
            MANAGER: "Manager 1"
          - NAME: "OUAPI2"
            DISTINGUISHED_NAME: "OU=OUAPI2,OU=OUS,DC=domain,DC=com"
            OU_NAME: "domain.com/OUS/OUAPI2"
            CITY: "Bangalore"
            COUNTRY: "India"
            STATE_PROVINCE: "-"
            OBJECT_GUID: "{715EC375-CC40-9A61-9C8E-DF9B7989D3FE}"
            MANAGER: "Manager 2"
    
    meta:
      type: object
      properties:
        start_index:
          type: integer
        limit:
          type: integer
        total_no_of_objects:
          type: integer

    update_ous_response:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/updated_ous_data'
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 10
            total_no_of_objects: 1

    updated_ous_data:
      type: object
      properties:
        object:
          type: object
          $ref: '#/components/schemas/object_data'
          example:
            Container Name: "OU=OUs,DC=domain,DC=com"
            OU Name: "APIOU1"
            Distinguished Name: "OU=APIOU1,OU=OUS,DC=domain,DC=com"
            Managed by: "CN=Manager 1,CN=Users,DC=domain,DC=com"
        status:
          $ref: '#/components/schemas/status'
          example:
            status_code: 1
            status_message: "Successfully Updated."

    object_data:
      type: object
      properties:
        OU Name:
          type: string
        Distinguished Name:
          type: string
        Container Name:
          type: string
        Managed by:
          type: string
    
    status:
      type: object
      properties:
        status_code:
          type: integer
        status_message:
          type: string

    api_attributes:
      type: object
      properties:
        name:
          type: string
          description: "Name of the OU."
        description:
          type: string
          description: "Description of the OU."
        OUName:
          type: string
          description: "The container path where the OU should reside."
        managedBy:
          type: string
          description: "Manager of the OU."
        street:
          type: string
          description: "Street address of the OU."
        state:
          type: string
          description: "State or province of the OU."
        l:
          type: string
          description: "City of the OU."
        postalCode:
          type: string
          description: "Postal code of the OU."
        country:
          type: string
          description: "Country of the OU."
        c:
          type: string
          description: "Two-letter country code of the OU."
        preventDeletion:
          type: boolean
          description: "Specifies whether the OU is protected from deletion."

    update_ous_body:
      type: object
      properties:
        data:
          type: object
          properties:
            attributes:
              type: object
              description: >
                The attributes of the OU to be updated.
              $ref: '#/components/schemas/api_attributes'
          description: >
            Data to be updated for the OU.
          example:
              attributes:
                name: "APIOU1"
                OUName: "OU=OUS,DC=domain,DC=com"
                managedBy: "Manager1"
                co: "India"
                extensionAttribute1: "Custom Value 1"

    bad_request_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000100"
        detail:
          type: string
          description: Detailed error message
          example: "Some columns given in fields parameter are invalid"
        title:
          type: string
          description: Short error message
          example: "Bad Request."
    unauthorized_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000101"
        detail:
          type: string
          description: Detailed error message
          example: "The given Authtoken is invalid."
        title:
          type: string
          description: Short error message
          example: "Unauthorized."
    internal_server_error_response:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: "00000000"
        detail:
          type: string
          description: Detailed error message
          example: "An internal server error occurred."
        title:
          type: string
          description: Short error message
          example: "Internal Server Error."
  securitySchemes:
    authToken:
      type: apiKey
      in: header
      name: Authorization
