@celigo/api-specs 0.2.205 → 0.2.207

package/dist/httpconnector.yml

@@ -204,6 +204,19 @@ paths:
             type: string
             format: objectId
           description: HTTP Connector ID.
+        - in: query
+          name: returnEverything
+          required: false
+          schema:
+            type: boolean
+          description: |-
+            When true, the response adds `httpConnectorResources` and
+            `httpConnectorEndpoints`: the connector's resources and the endpoints
+            under them, in one call. Only the exact value `true` fills them. Any
+            other non-empty value, including `false`, adds both arrays empty, and an
+            absent or empty parameter leaves them out. The `true` response is
+            streamed without a `Content-Length` header, and for a connector with
+            many endpoints it can exceed 1 MB.
       responses:
         '200':
           description: HTTP Connector retrieved successfully.
@@ -1951,6 +1964,649 @@ components:
             - '2023-05-20T11:45:32Z'
       required:
         - _id
+    ResourceField:
+      type: object
+      description: One field of the resource's records, optionally with nested child fields.
+      required:
+        - id
+      properties:
+        id:
+          type: string
+          description: Field identifier as it appears in the record.
+          examples:
+            - id
+        label:
+          type: string
+          description: Display label for the field.
+          examples:
+            - ID
+        description:
+          type: string
+          description: Help text describing the field.
+          examples:
+            - Record identifier
+        dataType:
+          type: string
+          description: Data type label for the field, stored as given.
+          examples:
+            - string
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Free-form metadata for the field.
+        resourceFields:
+          type: array
+          description: Child fields of an object or array field. Absent when the field is scalar.
+          items:
+            type: object
+            additionalProperties: true
+            description: Nested field with the same shape as its parent.
+    ResourceSupportedBySection:
+      type: object
+      description: |-
+        Conditions, pre-configured field values, required user inputs, and
+        fields to clear for one resource type (export or import) created from
+        this resource.
+      properties:
+        conditions:
+          type: array
+          description: |-
+            Expression-based filters referenced by `_conditionIds` in
+            `preConfiguredFields` and `fieldsUserMustSet` to apply those entries
+            conditionally.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                readOnly: true
+                description: Identifier of this condition, referenced by `_conditionIds` in field entries.
+                examples:
+                  - 5f8d43a1b9e5a80011a35f2c
+              condition:
+                $ref: '#/components/schemas/Filter'
+        preConfiguredFields:
+          type: array
+          description: Fields set automatically on the generated export or import. Not editable by the user.
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+                description: |-
+                  Dot-notation name of the setting in the connector's form. It is not always a literal
+                  path on the generated export or import: a form group such as `response` takes an
+                  object value (`{resourcePath: "customers"}`) that sets the step's
+                  `http.response.resourcePath`.
+                examples:
+                  - http.successMediaType
+                  - response
+              values:
+                type: array
+                description: Value(s) to assign. Typically a single-element array; entries may be any JSON type.
+                examples:
+                  - - json
+              _conditionIds:
+                type: array
+                description: Condition IDs that must be satisfied for this entry to apply. Always applies when absent.
+                items:
+                  type: string
+                  format: objectId
+                  examples:
+                    - 5f8d43a1b9e5a80011a35f2c
+        fieldsUserMustSet:
+          type: array
+          description: Fields the user must provide values for on the generated export or import.
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+                description: |-
+                  Dot-notation name of the setting the connector's form asks for: a step field such as
+                  `ignoreExisting` or `type`, or `mapping.fields.generate.<field>`, a destination field
+                  the import's mapping must produce.
+                examples:
+                  - name
+                  - ignoreExisting
+                  - mapping.fields.generate.customer.email
+              values:
+                type: array
+                description: Optional suggested or constrained values. Entries may be any JSON type.
+                examples:
+                  - - delta
+                    - test
+              _conditionIds:
+                type: array
+                description: Condition IDs that must be satisfied for this entry to apply.
+                items:
+                  type: string
+                  format: objectId
+                  examples:
+                    - 5f8d43a1b9e5a80011a35f2c
+              helpURL:
+                type: string
+                description: URL to documentation for this field.
+                examples:
+                  - https://docs.celigo.com/hc/en-us
+              labelOverride:
+                type: string
+                description: Custom label shown in the UI instead of the default.
+                examples:
+                  - Record name
+        fieldsToUnset:
+          type: array
+          description: Dot-notation paths to clear on the generated export or import.
+          items:
+            type: string
+            examples:
+              - http.paging
+    ResourceSupportedBy:
+      type: object
+      description: |-
+        Defaults the connector framework applies when a user builds an export or
+        an import on one of this resource's endpoints. Each section
+        pre-configures fields, lists the fields the user must still fill in, and
+        clears fields that do not apply.
+      properties:
+        export:
+          $ref: '#/components/schemas/ResourceSupportedBySection'
+        import:
+          allOf:
+            - $ref: '#/components/schemas/ResourceSupportedBySection'
+            - type: object
+              properties:
+                pathParameterToIdentifyExisting:
+                  type: string
+                  description: |-
+                    Path parameter whose value identifies the existing record on
+                    an update or upsert import. Needed only when the endpoint has
+                    more than one path parameter.
+                  examples:
+                    - id
+                lookupToIdentifyExisting:
+                  type: object
+                  description: |-
+                    Lookup the import runs to find out whether a record already
+                    exists before deciding between create and update. Both
+                    fields go together — sending one without the other is
+                    rejected.
+                  properties:
+                    _httpConnectorEndpointId:
+                      type: string
+                      format: objectId
+                      x-celigo-refModel: httpconnectorendpoints
+                      description: |-
+                        HTTP Connector Endpoint that performs the lookup. Must be
+                        an existing endpoint.
+                      examples:
+                        - 63987132784a39b73aae63ea
+                    extract:
+                      type: string
+                      description: Path in the lookup response to read the existing record's identifier from.
+                      examples:
+                        - data.0.id
+    HTTPConnectorResourceBase:
+      type: object
+      description: Writable fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          description: Human-readable name of the API resource this grouping represents (for example "Account", "Contact", "Order").
+          examples:
+            - Account
+        published:
+          type: boolean
+          default: false
+          description: |-
+            When true, the resource is visible to users of the connector's
+            published catalog. Only resources whose owner may publish HTTP
+            connectors appear to other accounts.
+        _httpConnectorId:
+          type: string
+          format: objectId
+          x-celigo-refModel: httpconnectors
+          description: |-
+            HTTP Connector this resource belongs to. Must be a connector owned by
+            the caller's account.
+          examples:
+            - 63987132784a39b73aae63cd
+        _httpConnectorApiId:
+          type: string
+          format: objectId
+          description: |-
+            API group (an entry of the connector's `apis[]`) this resource belongs
+            to. Set only for grouped connectors; flat connectors scope resources by
+            `_versionIds` instead.
+          examples:
+            - 63987132784a39b73aae63d0
+        _versionIds:
+          type: array
+          description: |-
+            Connector (or API group) versions this resource is available in. Each
+            id must be one of the connector's `versions[]._id` values.
+          items:
+            type: string
+            format: objectId
+          examples:
+            - - 63987132784a39b73aae63ce
+        _parentResourceId:
+          type: string
+          format: objectId
+          x-celigo-refModel: httpconnectorresources
+          description: |-
+            Parent resource when this resource is nested under another one (for
+            example "Order line" under "Order"). Omit for top-level resources;
+            cannot be combined with `isRoot: true`.
+          examples:
+            - 63987132784a39b73aae63e7
+        isRoot:
+          type: boolean
+          default: false
+          description: |-
+            When true, marks the resource as the root of a resource hierarchy.
+            Rejected together with `_parentResourceId`.
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Free-form metadata stored with the resource, for example Data Intelligence attributes.
+          examples:
+            - note: Primary sales object
+        resourceFields:
+          type: array
+          description: |-
+            Field catalog of the records this resource returns, used by tooling to
+            describe the API's payloads. Fields nest through their own
+            `resourceFields`.
+          items:
+            $ref: '#/components/schemas/ResourceField'
+        supportedBy:
+          $ref: '#/components/schemas/ResourceSupportedBy'
+    HTTPConnectorResource:
+      type: object
+      required:
+        - _id
+        - _httpConnectorId
+        - name
+        - published
+        - createdAt
+        - lastModified
+      description: |-
+        HTTP Connector Resource as returned by `GET /v1/httpconnectorresources`,
+        `GET /v1/httpconnectorresources/{_id}`, and the nested
+        `GET /v1/httpconnectors/{_httpConnectorId}/{_id}` — all three return the
+        same object. Optional fields that were never set are absent.
+      allOf:
+        - $ref: '#/components/schemas/HTTPConnectorResourceBase'
+        - type: object
+          properties:
+            _id:
+              type: string
+              format: objectId
+              readOnly: true
+              x-celigo-refModel: httpconnectorresources
+              description: |-
+                Unique identifier for the resource. Doubles as the
+                `_httpConnectorResourceId` path parameter of the HTTP Connector
+                Endpoints API.
+              examples:
+                - 63987132784a39b73aae63e7
+            createdAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: Timestamp when the resource was created.
+              examples:
+                - '2023-01-17T09:51:53.665Z'
+            lastModified:
+              type: string
+              format: date-time
+              readOnly: true
+              description: Timestamp when the resource was last updated. Changes on every PUT.
+              examples:
+                - '2024-05-23T07:00:31.350Z'
+    HTTPConnectorEndpointBase:
+      type: object
+      description: Writable fields shared by the request and response schemas.
+      properties:
+        name:
+          type: string
+          description: Human-readable name for this endpoint, shown when users pick an operation.
+          maxLength: 255
+          examples:
+            - List
+        description:
+          type: string
+          description: Help text describing what the endpoint does. Absent when never set.
+          maxLength: 10240
+          examples:
+            - Returns all answers for a question.
+        published:
+          type: boolean
+          default: false
+          description: |-
+            When true, this endpoint is visible in the connector's published
+            catalog. Kept as stored when omitted on PUT.
+        isBlob:
+          type: boolean
+          default: false
+          description: When true, this endpoint transfers binary (blob) content instead of records. Kept as stored when omitted on PUT.
+        isMappingRequired:
+          type: boolean
+          default: false
+          description: When true, users must configure field mappings before an import built on this endpoint can run.
+        _httpConnectorResourceIds:
+          type: array
+          minItems: 1
+          description: |-
+            HTTP Connector Resources this endpoint is listed under. Each id must
+            be a resource owned by the caller's account; the endpoint appears in
+            the nested listing of every resource named here.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: httpconnectorresources
+            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. Defaults to `name` when omitted.
+                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
+                default: input
+                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. A free-form text input when omitted.
+              values:
+                type: array
+                description: Predefined values offered when `dataType` is `select` or `multiselect`.
+                items:
+                  type: string
+                  examples:
+                    - open
+            required:
+              - name
+        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. Defaults to `name` when omitted.
+                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
+                default: input
+                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. A free-form text input when omitted.
+              values:
+                type: array
+                description: Predefined values offered when `dataType` is `select` or `multiselect`.
+                items:
+                  type: string
+                  examples:
+                    - open
+            required:
+              - name
+        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: |-
+            How the connector framework turns this endpoint into an export or an
+            import: which one it becomes, the fields it pre-configures, and the
+            fields the user must still fill in. Each entry's `path` names a setting
+            in the connector's form, which is not always a literal path on the
+            generated export or import.
+          x-celigo-ai-guidance:
+            - |-
+              Read against the published Shopify connector on 2026-10-21: the list-customers export
+              endpoint presets `response` to `{resourcePath: "customers"}` and also presets `delta`,
+              and asks for `type` (`delta` or `test`); the create-customer import endpoint asks for
+              `ignoreExisting` and for `mapping.fields.generate.customer.email`, `…first_name` and
+              `…last_name`.
+            - |-
+              Copy a path that is already a field of the step (`type`, `ignoreExisting`,
+              `http.response.resourcePath`). Set a form group such as `response` through the step
+              fields its value names (`{resourcePath: "customers"}` is `http.response.resourcePath`).
+              Treat `mapping.fields.generate.<field>` as a destination field the import's mapping must
+              produce, not a property to set.
+          required:
+            - type
+          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. Also
+                the value the nested listing's `supportedByType` filter matches.
+            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
+    HTTPConnectorEndpoint:
+      type: object
+      required:
+        - _id
+        - name
+        - method
+        - relativeURI
+        - published
+        - isBlob
+        - isMappingRequired
+        - mergePostBodyToPagingPostBody
+        - _httpConnectorResourceIds
+        - createdAt
+        - lastModified
+      description: |-
+        HTTP Connector Endpoint as returned by `GET /v1/httpconnectorendpoints`,
+        `GET /v1/httpconnectorendpoints/{_id}`, and the nested
+        `GET /v1/httpconnectors/{_httpConnectorId}/{_httpConnectorResourceId}/{_id}`
+        — all three return the same object. Optional fields that were never set
+        are absent.
+      allOf:
+        - $ref: '#/components/schemas/HTTPConnectorEndpointBase'
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            metadata:
+              type: object
+              description: |-
+                Endpoint metadata used by Data Intelligence tooling. Absent when
+                never set; Data Intelligence attributes can only be stored on a
+                published endpoint.
+              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
     HTTPConnector:
       type: object
       required:
@@ -2009,6 +2665,25 @@ components:
               readOnly: true
               examples:
                 - 2
+            httpConnectorResources:
+              type: array
+              readOnly: true
+              description: |-
+                Only present on GET /v1/httpconnectors/{_id} with a non-empty
+                `returnEverything`, and empty unless it is exactly `true`. The
+                connector's resources, sorted by `_id`: the same set
+                `GET /v1/httpconnectors/{_httpConnectorId}/httpconnectorresources` lists.
+              items:
+                $ref: '#/components/schemas/HTTPConnectorResource'
+            httpConnectorEndpoints:
+              type: array
+              readOnly: true
+              description: |-
+                Only present on GET /v1/httpconnectors/{_id} with a non-empty
+                `returnEverything`, and empty unless it is exactly `true`. The
+                endpoints of the returned resources, grouped in resource order.
+              items:
+                $ref: '#/components/schemas/HTTPConnectorEndpoint'
             metadata:
               type: object
               readOnly: true