openapi: 3.0.0
info:
  title: Groups API                                      # TITLE OF THE DOCUMENT (REQUIRED)
  description: 'The Groups API provides programmatic access to Active Directory (AD) groups. It offers endpoints to update group attributes and retrieve group details using filters, sorting, and pagination, enabling administrators to automate and streamline group management. Group records typically include membership information, scope, and description fields, and the API ensures they can be accessed or modified in a consistent and secure format.'
  contact: {}
  version: 2.0.0
servers:
  -
    url: 'http://admanagerplus:8080/api/v2'                       # PRODUCT URL
    description: 'API Endpoint'                            # URL DESCRIPTION
tags:
  -
    name: api-for-ad-groups                                    # TAG NAME SHOULD BE SAME AS DEFINED IN APP.YML TAGS & SAME AS YML FILE NAME (REQUIRED)
    description: 'Groups Endpoint'                      # DESCRIPTION ABOUT THE TAG NAME
security:
  - authToken: []
paths:
  /groups:
    get:
      tags:
        - api-for-ad-groups
      summary: List AD groups
      description: |
        The List AD Groups endpoint returns information about AD groups. You can refine results by applying filters, selecting specific fields, sorting the output, and using pagination to manage large datasets. This makes it easy to work with groups across one or more domains.
      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 groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/list_groups_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 group action, All group management actions
          - delegated-roles
          - All Groups Report 
    patch:
      tags:
        - api-for-ad-groups
      summary: Update AD Groups
      description: The Update AD Groups endpoint allows you to modify the properties of existing AD groups in bulk or individually. You can update core group details such as name, description, type, and OU, as well as advanced attributes like Exchange settings, membership, and nested group associations. <br> By sending the required payload, administrators can streamline group management tasks without needing to manually update groups from the ADManager Plus console.
      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_groups_body'
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_groups_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 group action, All group management actions
          - delegated-roles
          - Modify Groups Using CSV, Bulk Group 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'
    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
    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 group 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 groups. 
        <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: 'SAM_ACCOUNT_NAME,FULL_NAME,MEMBER_OF'
    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/products/ad-manager/active-directory-api/v2/filters/#overview">Filter section</a> for details.
        <br>
        <strong>Example:</strong> (SAM_ACCOUNT_NAME eq John) and (GROUP_NAME eq Doe)
      required: false
    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>Example:</strong> SAM_ACCOUNT_NAME,-GROUP_NAME
      required: false
      example: 'SAM_ACCOUNT_NAME,-GROUP_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
    domain:
      in: query
      name: domain
      description: >
        The AD domain where the requested operation is performed.
        <br>
        <strong>Example:</strong> domain1.com
      required: true
      example: domain1.com
      schema:
        type: string
  schemas:
    list_groups_response: 
      type: object
      properties:
        data:
          type: array
          example:
          - GROUP_NAME: TestGroup1
            GROUP_SCOPE: "Universal"
            DISTINGUISHED_NAME: "CN=TestGroup1,OU=Groups ou,DC=domain,DC=com"
            OU_NAME: "Groups"
            GROUP_TYPE: "Security"
            SID_STRING: "S-1-5-21-829236456-16713239527-3165918102-24259"
            OBJECT_GUID: "{3473E19D-48D1-4B65-8B9D-82923645627}"
            MANAGER: "Manager1"
            SAM_ACCOUNT_NAME: "TestGroup1"
          - GROUP_NAME: TestGroup2
            GROUP_SCOPE: "Global"
            DISTINGUISHED_NAME: "CN=TestGroup2,OU=Groups ou,DC=domain,DC=com"
            OU_NAME: "Groups"
            GROUP_TYPE: "Distribution"
            SID_STRING: "S-1-5-21-829236456-16713239527-3165918102-24260"
            OBJECT_GUID: "{3473E19D-48D1-4B65-8B9D-82923645628}"
            MANAGER: "Manager2"
            SAM_ACCOUNT_NAME: "TestGroup2"
        meta:
          $ref: '#/components/schemas/meta'
          example:
            start_index: 1
            limit: 10
            total_no_of_objects: 2

    groups_array:
      type: array
      items:
        example:
          - GROUP_NAME: TestGroup1
            GROUP_SCOPE: "Universal"
            DISTINGUISHED_NAME: "CN=TestGroup1,OU=Groups ou,DC=domain,DC=com"
            OU_NAME: "Groups"
            GROUP_TYPE: "Security"
            SID_STRING: "S-1-5-21-829236456-16713239527-3165918102-24259"
            OBJECT_GUID: "{3473E19D-48D1-4B65-8B9D-82923645627}"
            MANAGER: "Manager1"
            SAM_ACCOUNT_NAME: "TestGroup1"
          - GROUP_NAME: TestGroup2
            GROUP_SCOPE: "Global"
            DISTINGUISHED_NAME: "CN=TestGroup2,OU=Groups ou,DC=domain,DC=com"
            OU_NAME: "Groups"
            GROUP_TYPE: "Distribution"
            SID_STRING: "S-1-5-21-829236456-16713239527-3165918102-24260"
            OBJECT_GUID: "{3473E19D-48D1-4B65-8B9D-82923645628}"
            MANAGER: "Manager2"
            SAM_ACCOUNT_NAME: "TestGroup2"
    
    meta:
      type: object
      properties:
        start_index:
          type: integer
        limit:
          type: integer
        total_no_of_objects:
          type: integer

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

    updated_groups_data:
      type: object
      properties:
        object:
          type: object
          $ref: '#/components/schemas/object_data'
          example:
            SAM Account Name: "TestGroup2"
            Distinguished Name: "CN=TestGroup2,OU=Groups,DC=domain,DC=com"
            Email Proxy Addresses: "[SMTP:TestGroup2@domain.com]"
            Name: "TestGroup2"
        status:
          $ref: '#/components/schemas/status'
          example:
            status_code: 1
            status_message: "Successfully updated the group."

    object_data:
      type: object
      properties:
        SAM Account Name:
          type: string
        Distinguished Name:
          type: string
        Email Proxy Addresses:
          type: string
        Name:
          type: string
    
    status:
      type: object
      properties:
        status_code:
          type: integer
        status_message:
          type: string

    update_groups_body:
      type: object
      properties:
        data:
          type: object
          description:
            Data to be updated for the object.
          properties:
            attributes:
              type: object
              description: >
                Attributes of the object to be updated.  This can include Active directory attributes and Exchange attributes.
              properties:
                  sAMAccountName:
                    type: string
                    description: "The SAM account name of the group."
                  name:
                    type: string
                    description: "The name of the group."
                  description:
                    type: string
                    description: "The description of the group."
                  OUName:
                    type: string
                    description: "The OU where the group should reside."
                  mail:
                    type: string
                    description: "The email address of the group."
                  groupType:
                    type: string
                    description: "The type of the group (e.g., Security, Distribution)."
                  member:
                    type: string
                    description: "The members of the group."
                  memberOf:
                    type: string
                    description: "Groups that this group should be a member."
                  info:
                    type: string
                    description: "Notes attribute of the group."
                  displayName:
                    type: string
                    description: "The display name of the group."
                  displayNamePrintable:
                    type: string
                    description: "The printable display name of the group."
                  preventDeletion:
                    type: boolean
                    description: "Indicates whether the group can be deleted."
                  exchange:
                    type: object
                    description: "Exchange-related attributes for the group."
                    properties:
                      msExchAdminGroup:
                        type: string
                        description: "The administrative group associated with Exchange"
                      mailNickname:
                        type: string
                        description: "The email alias of the group, used as the mail nickname in Exchange."
                      delivContLength:
                        type: integer
                        description: "The maximum delivery size (in KB) allowed for the group."
                      authOrig:
                        type: string
                        description: "List of senders who are allowed to send messages to this group's members."
                      unauthOrig:
                        type: string
                        description: "List of senders who are blocked from sending messages to this groups' members."
                      proxyAddresses:
                        type: string
                        description: "Collection of proxy email addresses assigned to the group."
                      msExchHideFromAddressLists:
                        type: boolean
                        description: "Indicates whether the group is hidden from the Exchange Global Address List (GAL)."
          
          example:
              attributes:
                sAMAccountName: "TestGroup2"
                name: "TestGroup2"
                accountNameHistory: "st9v9;s9t3s;9st5"
                memberOf: "TestGroup3;TestGroup4"
                exchange: {
                  "msExchAdminGroup": "/o=Test/ou=Exchange Administrative Group (FYKLBOHF23SPDLT)",
                  "mailNickname": "TestGroup2",
                  "proxyAddresses": "SMTP:TestGroup2@domain.com"
                }

    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
