Application Research Groups API

openapi: 3.2.0
info:
  title: Application Research Open Resource Discovery (ORD) Groups API
  version: 1.12.0
  description: "The Open Resource Discovery (ORD) API provides access to ORD Documents which serve as wrappers \nfor ORD resources and taxonomy. This API enables discovery and management of API resources, \nevent resources, data products, entity types, capabilities, and integration dependencies.\n\nORD enables machine-readable self-description of systems and their capabilities, supporting\nautomated discovery, integration, and governance of enterprise APIs and services.\n"
  contact:
    name: ORD Specification Team
    url: https://open-resource-discovery.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.example.com/ord/v1
  description: Production server
- url: https://sandbox.example.com/ord/v1
  description: Sandbox server
security:
- oauth2:
  - ord:read
- bearerAuth: []
tags:
- name: Groups
  description: Group and Group Type operations
paths:
  /groups:
    get:
      tags:
      - Groups
      summary: Application Research List all Groups
      description: Retrieves a list of all Groups across all ORD Documents
      operationId: listGroups
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      - $ref: '#/components/parameters/GroupTypeFilterParam'
      responses:
        '200':
          description: Successfully retrieved list of Groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
              examples:
                groupList:
                  $ref: '#/components/examples/GroupListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /groups/{groupId}:
    get:
      tags:
      - Groups
      summary: Application Research Get a Group by Group ID
      description: Retrieves a specific Group by its Group ID
      operationId: getGroup
      parameters:
      - $ref: '#/components/parameters/GroupIdParam'
      responses:
        '200':
          description: Successfully retrieved Group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              examples:
                group:
                  $ref: '#/components/examples/GroupExample'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /group-types:
    get:
      tags:
      - Groups
      summary: Application Research List all Group Types
      description: Retrieves a list of all Group Types across all ORD Documents
      operationId: listGroupTypes
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/OffsetParam'
      responses:
        '200':
          description: Successfully retrieved list of Group Types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupTypeList'
              examples:
                groupTypeList:
                  $ref: '#/components/examples/GroupTypeListExample'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /group-types/{groupTypeId}:
    get:
      tags:
      - Groups
      summary: Application Research Get a Group Type by Group Type ID
      description: Retrieves a specific Group Type by its Group Type ID
      operationId: getGroupType
      parameters:
      - $ref: '#/components/parameters/GroupTypeIdParam'
      responses:
        '200':
          description: Successfully retrieved Group Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupType'
              examples:
                groupType:
                  $ref: '#/components/examples/GroupTypeExample'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    GroupType:
      type: object
      title: Group Type
      description: Defines the semantics of group assignments
      required:
      - groupTypeId
      - title
      properties:
        groupTypeId:
          type: string
          pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
        title:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          minLength: 1
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
        requestId:
          type: string
          description: Request ID for troubleshooting
    GroupList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Group'
        totalCount:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    GroupTypeList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/GroupType'
        totalCount:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
    Group:
      type: object
      title: Group
      description: Group instance that resources can be assigned to
      required:
      - groupId
      - groupTypeId
      - title
      properties:
        groupId:
          $ref: '#/components/schemas/GroupId'
        groupTypeId:
          type: string
          pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
        title:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          minLength: 1
    GroupId:
      type: string
      pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
      description: Valid Group ID
  examples:
    GroupExample:
      summary: Connectivity Capability Area Group
      value:
        groupId: sap.iot:capability-area:sap.iot:Connectivity
        groupTypeId: sap.iot:capability-area
        title: Connectivity
    GroupTypeExample:
      summary: IoT Capability Area Group Type
      value:
        groupTypeId: sap.iot:capability-area
        title: IoT Capability Area
        description: Logical grouping of IoT platform capabilities
    InternalServerErrorExample:
      summary: Internal Server Error
      value:
        code: INTERNAL_SERVER_ERROR
        message: An unexpected error occurred. Please try again later.
        requestId: req-12345-abcde
    NotFoundErrorExample:
      summary: Not Found Error
      value:
        code: NOT_FOUND
        message: The requested resource was not found
        requestId: req-12345-abcde
    GroupListExample:
      summary: List of Groups
      value:
        items:
        - groupId: sap.iot:capability-area:sap.iot:Connectivity
          groupTypeId: sap.iot:capability-area
          title: Connectivity
        - groupId: sap.iot:capability-area:sap.iot:Analytics
          groupTypeId: sap.iot:capability-area
          title: Analytics
        totalCount: 2
        limit: 20
        offset: 0
    BadRequestErrorExample:
      summary: Bad Request Error
      value:
        code: BAD_REQUEST
        message: Invalid request parameters
        details:
        - field: ordId
          message: ORD ID must match the required pattern
        requestId: req-12345-abcde
    GroupTypeListExample:
      summary: List of Group Types
      value:
        items:
        - groupTypeId: sap.iot:capability-area
          title: IoT Capability Area
          description: Logical grouping of IoT platform capabilities
        - groupTypeId: sap.iot:use-case
          title: IoT Use Case
          description: Grouping by supported IoT use case scenarios
        totalCount: 2
        limit: 20
        offset: 0
  parameters:
    GroupTypeFilterParam:
      name: groupTypeId
      in: query
      description: Filter groups by group type ID
      schema:
        type: string
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    OffsetParam:
      name: offset
      in: query
      description: Number of items to skip
      schema:
        type: integer
        minimum: 0
        default: 0
    GroupIdParam:
      name: groupId
      in: path
      required: true
      description: Group ID
      schema:
        type: string
        pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+):([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
      example: sap.iot:capability-area:sap.iot:Connectivity
    GroupTypeIdParam:
      name: groupTypeId
      in: path
      required: true
      description: Group Type ID
      schema:
        type: string
        pattern: ^([a-z0-9-]+(?:[.][a-z0-9-]+)*):([a-zA-Z0-9._\-\/]+)$
      example: sap.iot:capability-area
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            notFound:
              $ref: '#/components/examples/NotFoundErrorExample'
    BadRequest:
      description: Bad request - invalid input parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            badRequest:
              $ref: '#/components/examples/BadRequestErrorExample'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            serverError:
              $ref: '#/components/examples/InternalServerErrorExample'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication
      flows:
        clientCredentials:
          tokenUrl: /oauth/token
          scopes:
            ord:read: Read access to ORD resources
            ord:write: Write access to ORD resources
            ord:admin: Administrative access to ORD resources
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT