@celigo/api-specs 0.2.1

package/dist/httpconnectorendpoint.yml

@@ -0,0 +1,722 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: HTTP Connector Endpoints
+  description: API for managing Celigo HTTP Connector Endpoints — the individual method + URI operations under an HTTP Connector Resource.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: HTTP Connector Endpoints
+    description: |-
+      HTTP Connector Endpoints define the individual API operations (method +
+      URI) available under an HTTP Connector Resource. Each endpoint specifies
+      its HTTP method, relative URI template, query/path parameter definitions,
+      and supported-by rules that control how exports and imports are
+      pre-configured when users select this endpoint.
+
+      Endpoints are classified by `supportedBy.type`:
+      - **export** — reads data from the target system.
+      - **import** — writes data to the target system.
+
+      ## HTTP connector endpoint schema
+
+      {% openapi-schemas spec="httpconnectorendpoint" schemas="HTTPConnectorEndpoint" grouped="true" %}
+paths:
+  /v1/httpconnectors/{_httpConnectorId}/{_httpConnectorResourceId}/httpconnectorendpoints:
+    get:
+      x-internal: false
+      operationId: listHttpConnectorEndpoints
+      tags:
+        - HTTP Connector Endpoints
+      summary: List HTTP Connector Endpoints for a connector resource
+      description: |-
+        Returns all endpoints defined under the given HTTP Connector Resource.
+        The list response is abridged — only `_id`, `name`, `createdAt`, and
+        `lastModified` are returned. Use the by-ID endpoint for the full object
+        including `method`, `relativeURI`, and `supportedBy`.
+      parameters:
+        - name: limit
+          in: query
+          description: Maximum number of records to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+        - $ref: '#/components/parameters/After'
+        - in: path
+          name: _httpConnectorId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: httpconnectors
+            examples:
+              - 62a1f2c3b4d5e6f7a8b9c0d1
+          description: HTTP Connector ID.
+        - in: path
+          name: _httpConnectorResourceId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 63987132784a39b73aae63e7
+          description: HTTP Connector Resource ID.
+        - in: query
+          name: supportedByType
+          schema:
+            type: string
+            enum:
+              - import
+              - export
+            x-enumDescriptions:
+              import: Return only endpoints used as imports (write to target system).
+              export: Return only endpoints used as exports (read from target system).
+          description: Filter endpoints by their supported-by direction.
+        - in: query
+          name: publishedOnly
+          schema:
+            type: boolean
+          description: When true, only return published endpoints.
+      responses:
+        '200':
+          description: Successfully retrieved list of HTTP Connector Endpoints.
+          headers:
+            Link:
+              description: |-
+                RFC-5988 pagination links. When more pages remain, includes a `<...>; rel="next"` entry;
+                absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/ListItem'
+              examples:
+                two_endpoints:
+                  value:
+                    - _id: 63987132784a39b73aae63e8
+                      name: List
+                      createdAt: '2023-01-17T09:52:06.871Z'
+                      lastModified: '2024-05-23T07:00:46.308Z'
+                    - _id: 63987132784a39b73aae63e9
+                      name: Read
+                      createdAt: '2023-01-17T09:52:07.219Z'
+                      lastModified: '2024-05-23T07:00:46.660Z'
+        '204':
+          description: No endpoints exist for this resource (or none match the filter).
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/httpconnectors/{_httpConnectorId}/{_httpConnectorResourceId}/{_id}:
+    get:
+      x-internal: false
+      operationId: getHttpConnectorEndpointById
+      tags:
+        - HTTP Connector Endpoints
+      summary: Get an HTTP connector endpoint
+      description: |-
+        Retrieves the full HTTP Connector Endpoint including `method`,
+        `relativeURI`, `queryParameters`, `pathParameters`, and `supportedBy`
+        details omitted from the list endpoint.
+      parameters:
+        - in: path
+          name: _httpConnectorId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: httpconnectors
+            examples:
+              - 62a1f2c3b4d5e6f7a8b9c0d1
+          description: HTTP Connector ID.
+        - in: path
+          name: _httpConnectorResourceId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 63987132784a39b73aae63e7
+          description: HTTP Connector Resource ID.
+        - in: path
+          name: _id
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: httpconnectorendpoints
+            examples:
+              - 63987132784a39b73aae63e8
+          description: HTTP Connector Endpoint ID.
+      responses:
+        '200':
+          description: HTTP Connector Endpoint retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPConnectorEndpoint'
+              examples:
+                export_endpoint:
+                  value:
+                    _id: 63987132784a39b73aae63e8
+                    name: List
+                    createdAt: '2023-01-17T09:52:06.871Z'
+                    lastModified: '2024-05-23T07:00:46.308Z'
+                    published: true
+                    isBlob: false
+                    isMappingRequired: false
+                    mergePostBodyToPagingPostBody: false
+                    _httpConnectorResourceIds:
+                      - 63987132784a39b73aae63e7
+                    method: GET
+                    relativeURI: /api/public/answer/?page={{{export.http.paging.page}}}
+                    queryParameters:
+                      - name: question_id
+                        label: Question ID
+                        description: Include only answers for a question with the specified ID.
+                        required: false
+                        dataType: input
+                    supportedBy:
+                      type: export
+                      preConfiguredFields:
+                        - path: response
+                          values:
+                            - resourcePath: results
+                      fieldsUserMustSet:
+                        - path: type
+                          values:
+                            - delta
+                            - test
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    After:
+      name: after
+      in: query
+      required: false
+      description: |-
+        Opaque cursor for forward pagination. Pass the value from the `Link`
+        response header (`rel="next"`) to fetch the next page.
+      schema:
+        type: string
+  schemas:
+    ListItem:
+      type: object
+      description: |-
+        Abridged HTTP Connector Endpoint returned in list responses. Only
+        includes identity and timestamp fields. Use the by-ID endpoint for
+        the full object including method, relativeURI, and supportedBy.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-refModel: httpconnectorendpoints
+          examples:
+            - 63987132784a39b73aae63e8
+        name:
+          type: string
+          description: Human-readable name for this endpoint.
+          examples:
+            - List
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          examples:
+            - '2023-01-17T09:52:06.871Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          examples:
+            - '2024-05-23T07:00:46.308Z'
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    HTTPConnectorEndpointBase:
+      type: object
+      description: Writable fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          description: Human-readable name for this endpoint
+          maxLength: 255
+          examples:
+            - List
+        description:
+          type: string
+          description: Optional endpoint description
+          maxLength: 10240
+          examples:
+            - Returns all answers for a question.
+        published:
+          type: boolean
+          description: When true, this endpoint is published and available for use.
+        isBlob:
+          type: boolean
+          description: When true, this endpoint handles binary/blob data.
+          default: false
+        isMappingRequired:
+          type: boolean
+          description: When true, field mapping is required for this endpoint.
+          default: false
+        _httpConnectorResourceIds:
+          type: array
+          description: References to HTTP Connector Resources associated with this endpoint
+          items:
+            type: string
+            format: objectId
+            examples:
+              - 63987132784a39b73aae63e7
+        method:
+          type: string
+          enum:
+            - GET
+            - PUT
+            - POST
+            - PATCH
+            - DELETE
+            - HEAD
+          x-enumDescriptions:
+            GET: Retrieve data from the endpoint.
+            PUT: Replace data at the endpoint.
+            POST: Submit data to the endpoint.
+            PATCH: Partially update data at the endpoint.
+            DELETE: Remove data at the endpoint.
+            HEAD: Probe the endpoint without transferring a response body.
+          description: |-
+            HTTP method for this endpoint. Required on save; lowercase input is
+            uppercased automatically.
+        relativeURI:
+          type: string
+          description: Relative URI template for this endpoint
+          examples:
+            - /api/public/answer/?page={{{export.http.paging.page}}}
+        mergePostBodyToPagingPostBody:
+          type: boolean
+          description: When true, merges the postBody into pagingPostBody for paginated requests.
+          default: false
+        queryParameters:
+          type: array
+          description: Query parameter definitions
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                description: Parameter name as it appears in the request query string.
+                examples:
+                  - question_id
+              label:
+                type: string
+                description: Label shown to users in the UI for this parameter.
+                examples:
+                  - Question ID
+              description:
+                type: string
+                description: Help text shown to users explaining what this parameter does.
+                examples:
+                  - Include only answers for a question with the specified ID.
+              required:
+                type: boolean
+                description: When true, the user must supply a value for this parameter.
+              dataType:
+                type: string
+                enum:
+                  - input
+                  - date
+                  - select
+                  - multiselect
+                  - array
+                  - number
+                x-enumDescriptions:
+                  input: Free-form text input field.
+                  date: Date picker input field.
+                  select: Single-value dropdown selection.
+                  multiselect: Multi-value dropdown selection.
+                  array: Array of values.
+                  number: Numeric input field.
+                description: UI input type used to collect the parameter value.
+              values:
+                type: array
+                description: Predefined values offered when `dataType` is `select` or `multiselect`.
+                items:
+                  type: string
+                  examples:
+                    - open
+            required:
+              - name
+              - label
+        pathParameters:
+          type: array
+          description: Path parameter definitions
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                description: Parameter name as it appears in the `relativeURI` template.
+                examples:
+                  - id
+              label:
+                type: string
+                description: Label shown to users in the UI for this parameter.
+                examples:
+                  - Answer ID
+              description:
+                type: string
+                description: Help text shown to users explaining what this parameter does.
+                examples:
+                  - Identifier of the answer to retrieve.
+              required:
+                type: boolean
+                description: When true, the user must supply a value for this parameter.
+              dataType:
+                type: string
+                enum:
+                  - input
+                  - date
+                  - select
+                  - multiselect
+                  - array
+                  - number
+                x-enumDescriptions:
+                  input: Free-form text input field.
+                  date: Date picker input field.
+                  select: Single-value dropdown selection.
+                  multiselect: Multi-value dropdown selection.
+                  array: Array of values.
+                  number: Numeric input field.
+                description: UI input type used to collect the parameter value.
+              values:
+                type: array
+                description: Predefined values offered when `dataType` is `select` or `multiselect`.
+                items:
+                  type: string
+                  examples:
+                    - open
+            required:
+              - name
+              - label
+        resourceFields:
+          type: array
+          description: Resource field definitions for this endpoint
+          items:
+            type: object
+            properties:
+              type:
+                type: string
+                enum:
+                  - inclusion
+                  - exclusion
+                x-enumDescriptions:
+                  inclusion: Only the listed fields are included in the resource.
+                  exclusion: All fields except the listed ones are included in the resource.
+                description: Whether `fields` lists the fields to include or to exclude.
+              fields:
+                type: array
+                description: Field names the inclusion or exclusion rule applies to.
+                items:
+                  type: string
+                  examples:
+                    - question_id
+              _httpConnectorResourceId:
+                type: string
+                format: objectId
+                description: HTTP Connector Resource these field rules apply to.
+                examples:
+                  - 63987132784a39b73aae63e7
+            required:
+              - type
+              - fields
+              - _httpConnectorResourceId
+        supportedBy:
+          type: object
+          description: Supported-by configuration for this endpoint (framework-defined)
+          properties:
+            type:
+              type: string
+              enum:
+                - import
+                - export
+              x-enumDescriptions:
+                import: This endpoint is used as an import (writes data to the target system).
+                export: This endpoint is used as an export (reads data from the target system).
+              description: Whether this endpoint is consumed as an import or an export.
+            conditions:
+              type: array
+              description: Expression-based filters that control when entries in `preConfiguredFields` and `fieldsUserMustSet` apply.
+              items:
+                type: object
+                additionalProperties: true
+            preConfiguredFields:
+              type: array
+              description: Fields automatically set to predefined values on the generated export or import. Not editable by the user.
+              items:
+                type: object
+                additionalProperties: true
+            fieldsUserMustSet:
+              type: array
+              description: Fields the user must provide values for on the generated export or import.
+              items:
+                type: object
+                additionalProperties: true
+            fieldsToUnset:
+              type: array
+              description: Dot-notation paths of fields to remove from the generated export or import configuration.
+              items:
+                type: string
+                examples:
+                  - http.paging.method
+            pathParameterToIdentifyExisting:
+              type: string
+              description: Path parameter whose value identifies an existing record in the target application.
+              examples:
+                - id
+            lookupToIdentifyExisting:
+              type: object
+              description: Lookup used to determine whether a record already exists in the target application.
+              properties:
+                _httpConnectorEndpointId:
+                  type: string
+                  format: objectId
+                  description: HTTP Connector Endpoint used to perform the lookup.
+                  x-celigo-refModel: httpconnectorendpoints
+                  examples:
+                    - 63987132784a39b73aae63ea
+                extract:
+                  type: string
+                  description: Path in the lookup response from which to extract the existing record's identifier.
+                  examples:
+                    - results.0.id
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    HTTPConnectorEndpoint:
+      type: object
+      required:
+        - _id
+        - name
+        - method
+        - relativeURI
+        - published
+        - createdAt
+        - lastModified
+      description: HTTP Connector Endpoint object as returned by the detail (by-ID) endpoint.
+      allOf:
+        - $ref: '#/components/schemas/HTTPConnectorEndpointBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _userId:
+              type: string
+              format: objectId
+              description: Owner user id
+              readOnly: true
+              x-celigo-refModel: users
+              examples:
+                - 55f9d6e0c1a2b3d4e5f60718
+            metadata:
+              type: object
+              readOnly: true
+              description: |-
+                Endpoint metadata used by Data Intelligence tooling. Returned
+                only by the detail (by-ID) endpoint — list responses omit it.
+              properties:
+                di:
+                  type: object
+                  description: Data Intelligence attributes for this endpoint.
+                  properties:
+                    isListEndpoint:
+                      type: boolean
+                      description: When true, the endpoint returns a list of records rather than a single record.
+                    responseFields:
+                      type: array
+                      description: Fields Data Intelligence expects in this endpoint's response records.
+                      items:
+                        type: object
+                        properties:
+                          id:
+                            type: string
+                            description: Field path within a response record.
+                            examples:
+                              - email
+                          dataType:
+                            type: string
+                            description: Data type of the field.
+                            examples:
+                              - string
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+x-enable-proxy: true
+x-internal: false