@celigo/api-specs 0.2.1

package/dist/httpconnectorresource.yml

@@ -0,0 +1,396 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: HTTP Connector Resources
+  description: API for reading Celigo HTTP Connector Resources — logical API resource groupings within an HTTP Connector.
+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 Resources
+    description: |-
+      API for reading HTTP Connector Resource objects in Celigo.
+      HTTP Connector Resources represent logical API resource groupings (e.g. "Account",
+      "Contact", "Order") within an HTTP Connector. Each resource is associated with one
+      or more connector versions and contains HTTP Connector Endpoints that define the
+      available operations.
+
+      These endpoints are **read-only** — creating, updating, and deleting HTTP Connector
+      Resources is only available through the Celigo UI (session authentication).
+
+      ## HTTP connector resource schema
+
+      {% openapi-schemas spec="httpconnectorresource" schemas="HTTPConnectorResource" grouped="true" %}
+paths:
+  /v1/httpconnectors/{_httpConnectorId}/httpconnectorresources:
+    get:
+      x-internal: false
+      operationId: listHttpConnectorResources
+      tags:
+        - HTTP Connector Resources
+      summary: List HTTP Connector Resources for a connector
+      description: |-
+        Returns all resources (logical API groupings) defined under the given
+        HTTP Connector.
+
+        The list response is abridged — it omits `published` and
+        `_httpConnectorId` compared to the detail endpoint. Use
+        `GET /v1/httpconnectors/{_httpConnectorId}/{_id}` for the full object.
+
+        Each resource's `_id` doubles as the `_httpConnectorResourceId` path
+        parameter used by the HTTP Connector Endpoints API.
+      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:
+              - 63987132784a39b73aae63cd
+          description: HTTP Connector ID
+      responses:
+        '200':
+          description: Successfully retrieved list of HTTP Connector Resources
+          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_resources:
+                  value:
+                    - _id: 63987132784a39b73aae63e7
+                      name: Answer
+                      createdAt: '2023-01-17T09:51:53.665Z'
+                      lastModified: '2024-05-23T07:00:31.350Z'
+                      _versionIds:
+                        - 63987132784a39b73aae63ce
+                    - _id: 63987132784a39b73aae63e1
+                      name: Attribute
+                      createdAt: '2023-01-17T09:51:52.118Z'
+                      lastModified: '2024-05-23T07:00:29.858Z'
+                      _versionIds:
+                        - 63987132784a39b73aae63ce
+        '204':
+          description: No resources exist for this connector
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/httpconnectors/{_httpConnectorId}/{_id}:
+    get:
+      x-internal: false
+      operationId: getHttpConnectorResourceById
+      tags:
+        - HTTP Connector Resources
+      summary: Get an HTTP connector resource
+      description: |-
+        Retrieves a specific HTTP Connector Resource by its unique identifier.
+
+        The path uses a shortcut form: `/v1/httpconnectors/{_httpConnectorId}/{_id}`
+        where `{_id}` is the resource ID directly under the connector. The longer
+        form `/v1/httpconnectors/{_httpConnectorId}/httpconnectorresources/{_id}`
+        is not supported and fails with an `invalid_ref` error.
+
+        The detail response includes `published` and `_httpConnectorId` fields
+        that are omitted from the list endpoint.
+      parameters:
+        - in: path
+          name: _httpConnectorId
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: httpconnectors
+            examples:
+              - 63987132784a39b73aae63cd
+          description: HTTP Connector ID
+        - in: path
+          name: _id
+          required: true
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: httpconnectorresources
+            examples:
+              - 63987132784a39b73aae63e7
+          description: HTTP Connector Resource ID
+      responses:
+        '200':
+          description: HTTP Connector Resource retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HTTPConnectorResource'
+              examples:
+                detail:
+                  value:
+                    _id: 63987132784a39b73aae63e7
+                    name: Answer
+                    createdAt: '2023-01-17T09:51:53.665Z'
+                    lastModified: '2024-05-23T07:00:31.350Z'
+                    published: true
+                    _httpConnectorId: 63987132784a39b73aae63cd
+                    _versionIds:
+                      - 63987132784a39b73aae63ce
+        '400':
+          description: Invalid resource ID
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_ref:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _httpConnectorResourceId.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: |-
+            Resource not found or not published. Also returned when the
+            `_httpConnectorId` is valid but the resource ID doesn't belong to it.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                not_found:
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: httpConnectorResource not found or not published.
+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 Resource as returned in list responses. Omits
+        `published` and `_httpConnectorId` compared to the detail response.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: Unique identifier
+          readOnly: true
+          x-celigo-refModel: httpconnectorresources
+          examples:
+            - 63987132784a39b73aae63e7
+        name:
+          type: string
+          description: Resource name
+          examples:
+            - Account
+        _versionIds:
+          type: array
+          description: Connector version IDs this resource belongs to
+          items:
+            type: string
+            format: objectId
+            examples:
+              - 63987132784a39b73aae63ce
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when created
+          examples:
+            - '2023-01-17T09:51:53.665Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when last modified
+          examples:
+            - '2024-05-23T07:00:29.858Z'
+    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
+    HTTPConnectorResource:
+      type: object
+      required:
+        - _id
+        - _httpConnectorId
+        - name
+        - published
+        - createdAt
+        - lastModified
+      description: HTTP Connector Resource object as returned by the API
+      properties:
+        _id:
+          type: string
+          format: objectId
+          description: Unique identifier for the HTTP Connector Resource
+          readOnly: true
+          x-celigo-refModel: httpconnectorresources
+          examples:
+            - 63987132784a39b73aae63e7
+        name:
+          type: string
+          description: Human-readable name for this resource (e.g. "Account", "Contact", "Order")
+          examples:
+            - Account
+        published:
+          type: boolean
+          description: When true, this resource is published and visible to users.
+        _httpConnectorId:
+          type: string
+          format: objectId
+          description: |-
+            Parent HTTP Connector ID. Only present in the detail (by-ID) response,
+            omitted from list responses.
+          readOnly: true
+          x-celigo-refModel: httpconnectors
+          examples:
+            - 63987132784a39b73aae63cd
+        _versionIds:
+          type: array
+          description: Connector version IDs this resource belongs to
+          items:
+            type: string
+            format: objectId
+            examples:
+              - 63987132784a39b73aae63ce
+        createdAt:
+          type: string
+          format: date-time
+          description: Timestamp when created
+          readOnly: true
+          examples:
+            - '2023-01-17T09:51:53.665Z'
+        lastModified:
+          type: string
+          format: date-time
+          description: Timestamp when last modified
+          readOnly: true
+          examples:
+            - '2024-05-23T07:00:31.350Z'
+  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.
+x-enable-proxy: true
+x-internal: false