openapi: 3.0.3
info:
  title: DotAAS Part 2 | HTTP/REST | Concept Description Repository Service Specification
  description: >-
    The ConceptDescription Repository Service Specification as part of [Specification of the Asset Administration Shell: Part 2](https://industrialdigitaltwin.org/en/content-hub/aasspecifications).  
  
    Copyright: Industrial Digital Twin Association (IDTA) March 2023
  contact:
    name: Industrial Digital Twin Association (IDTA)
    email: info@idtwin.org
  license: 
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
  version: V3.2.0_SSP-001
  x-profile-identifier: https://admin-shell.io/aas/API/3/2/ConceptDescriptionRepositoryServiceSpecification/SSP-001
  termsOfService: https://github.com/admin-shell-io/aas-specs-metamodel
servers:
- url: 'https://admin-shell.io/api/v3/'
- url: 'https://example.com/'
paths:
  /concept-descriptions:
    get:
      tags:
        - Concept Description Repository API
      summary: Returns all Concept Descriptions
      operationId: GetAllConceptDescriptions
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllConceptDescriptions/3/2
        - https://admin-shell.io/aas/API/GetAllConceptDescriptionsByIdShort/3/2
        - https://admin-shell.io/aas/API/GetAllConceptDescriptionsByIsCaseOf/3/2
        - https://admin-shell.io/aas/API/GetAllConceptDescriptionsByDataSpecificationReference/3/2
      parameters:
        - name: idShort
          in: query
          description: The Concept Description’s IdShort
          required: false
          style: form
          explode: true
          schema:
            type: string
        - name: isCaseOf
          in: query
          description: IsCaseOf reference (UTF8-BASE64-URL-encoded)
          required: false
          style: form
          explode: true
          schema:
            type: string
        - name: dataSpecificationRef
          in: query
          description: DataSpecification reference (UTF8-BASE64-URL-encoded)
          required: false
          style: form
          explode: true
          schema:
            type: string
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Limit'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Cursor'
      responses:
        '200':
          description: Requested Concept Descriptions
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/GetConceptDescriptionsResult'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    post:
      tags:
        - Concept Description Repository API
      summary: Creates a new Concept Description
      operationId: PostConceptDescription
      x-semanticIds:
        - https://admin-shell.io/aas/API/PostConceptDescription/3/2
      requestBody:
        description: Concept Description object
        content:
          application/json:
            schema:
              $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/ConceptDescription'
        required: true
      responses:
        '201':
          description: Concept Description created successfully
          headers:
            Location:
              description: URL of the newly created resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/ConceptDescription'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '409':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/conflict'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /concept-descriptions/$recent-changes:
    get:
      tags:
        - Concept Description Repository API
      summary: Returns all Concept Descriptions that have been changed recently
      operationId: GetAllConceptDescriptionRecentChanges
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetAllConceptDescriptionRecentChanges/3/2
      parameters:
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/CreatedFrom'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/UpdatedFrom'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Limit'
        - $ref: '../Part2-API-Schemas/openapi.yaml#/components/parameters/Cursor'
      responses:
        '200':
          description: Requested list of recently changed Concept Descriptions
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/GetAllConceptDescriptionsRecentChangesResult'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '401':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/unauthorized'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /concept-descriptions/{cdIdentifier}:
    get:
      tags:
        - Concept Description Repository API
      summary: Returns a specific Concept Description
      operationId: GetConceptDescriptionById
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetConceptDescriptionById/3/2
      parameters:
        - name: cdIdentifier
          in: path
          description: The Concept Description’s unique id (UTF8-BASE64-URL-encoded)
          required: true
          style: simple
          explode: true
          schema:
            type: string
      responses:
        '200':
          description: Requested Concept Description
          content:
            application/json:
              schema:
                $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/ConceptDescription'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    put:
      tags:
        - Concept Description Repository API
      summary: Creates or updates an existing Concept Description
      operationId: PutConceptDescriptionById
      x-semanticIds:
        - https://admin-shell.io/aas/API/PutConceptDescriptionById/3/2
      parameters:
        - name: cdIdentifier
          in: path
          description: The Concept Description’s unique id (UTF8-BASE64-URL-encoded)
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        description: Concept Description object
        content:
          application/json:
            schema:
              $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/ConceptDescription'
        required: true
      responses:
        '201':
          description: Concept Description created successfully
          headers:
            Location:
              description: URL of the newly created resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/ConceptDescription'
        '204':
          description: Concept Description updated successfully
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
    delete:
      tags:
        - Concept Description Repository API
      summary: Deletes a Concept Description
      operationId: DeleteConceptDescriptionById
      x-semanticIds:
        - https://admin-shell.io/aas/API/DeleteConceptDescriptionById/3/2
      parameters:
        - name: cdIdentifier
          in: path
          description: The Concept Description’s unique id (UTF8-BASE64-URL-encoded)
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '204':
          description: Concept Description deleted successfully
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '404':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/not-found'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /serialization:
    get:
      tags:
        - Serialization API
      summary: Returns an appropriate serialization based on the specified format (see SerializationFormat)
      operationId: GenerateSerializationByIds
      x-semanticIds:
        - https://admin-shell.io/aas/API/GenerateSerializationByIds/3/2
      parameters:
        - name: aasIds
          in: query
          description: The Asset Administration Shells' unique ids (UTF8-BASE64-URL-encoded)
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: submodelIds
          in: query
          description: The Submodels' unique ids (UTF8-BASE64-URL-encoded)
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
        - name: includeConceptDescriptions
          in: query
          description: Include Concept Descriptions?
          style: form
          explode: true
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: Requested serialization based on SerializationFormat
          content:
            application/aas+zip:
              schema:
                description: AASX package
                type: string
                format: binary
            application/json:
              schema:
                $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/Environment'
            application/xml:
              schema:
                $ref: '../Part1-MetaModel-Schemas/openapi.yaml#/components/schemas/Environment'
        '400':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/bad-request'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'
        '500':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/internal-server-error'
        default:
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/default'
  /description:
    get:
      tags:
        - Description API
      summary: Returns the self-describing information of a network resource (ServiceDescription)
      operationId: GetSelfDescription
      x-semanticIds:
        - https://admin-shell.io/aas/API/GetSelfDescription/3/2
      responses:
        '200':
          description: Requested Description
          content:
            application/json:
              schema:
                $ref: '../Part2-API-Schemas/openapi.yaml#/components/schemas/ServiceDescription'
        '403':
          $ref: '../Part2-API-Schemas/openapi.yaml#/components/responses/forbidden'