Improve Generic HTTP integration docs - Phase 1

Matarp13 · Matarp13 · commit a312042caba4 · 2025-11-02T18:22:32.000+02:00
- Add JQ reference link in prerequisites
- Add two-step setup link in overview
- Add descriptive text before each interactive step
- Fix field deselection (toggle ID/Title buttons)
- Auto-select first array in JSON response
- Auto-generate blueprint ID and title with singularization
- Update form hints with explicit defaults
- Simplify configuration explanations
- Remove redundant copy buttons
- Fix mapping generation (query and blueprint quoting)
- Fix authentication config (use apiToken/apiKey/username+password)
- Fix image versioning (use integration.version instead of image.tag)
- Update to version 0.1.5-dev
- Add pluralize dependency for accurate singularization
diff --git a/docs/build-your-software-catalog/custom-integration/ocean-http/build-your-integration.md b/docs/build-your-software-catalog/custom-integration/ocean-http/build-your-integration.md
@@ -22,24 +22,47 @@ This interactive guide will help you generate everything you need to connect you
 
 ## Step 1: Configure Your API
 
-Set up the connection details for your API:
+Set up the connection details for your API. These settings apply globally to all endpoints you'll sync from this API.
+
+**What you're configuring:**
+- **Base URL**: The root URL that all endpoint paths will be appended to
+- **Authentication**: How your API verifies requests (bearer token, API key, basic auth, or none)
+- **Pagination** (optional): How to fetch data across multiple pages if your API uses pagination
+- **Performance settings** (optional): Timeouts, concurrent requests, SSL verification
+
+Think of this as setting up the "connection" - these settings will be used for every API call the integration makes.
 
 <Step1ApiConfig />
 
 ---
 
 ## Step 2: Choose What Data to Sync
 
-Select an endpoint and configure which fields to ingest into Port:
+Now that your API connection is configured, let's define what data to sync. This step helps you map a specific API endpoint to a Port blueprint.
+
+**What you'll do:**
+1. **Specify the endpoint path** (e.g., `/api/v1/users`) that you want to sync
+2. **Paste a sample API response** so we can detect the data structure
+3. **Select the data path** - tell us where the array of items is in the response (e.g., `.data`, `.users`, or root array)
+4. **Configure the blueprint** - give it an identifier and title
+5. **Choose which fields to sync** - select the fields you want to ingest and mark which field is the unique identifier
+
+The builder will automatically detect field types (string, number, boolean, email, date, URL) from your sample response.
 
 <Step2DataMapping />
 
 ---
 
 ## Step 3: Install and Create in Port
 
-Use the commands and configurations generated from your selections above.
+You're all set! Based on your configuration, we've generated everything you need:
+
+**What you'll get:**
+- **Installation commands** (Helm or Docker) with all your settings pre-configured
+- **Blueprint JSON** to create the data model in Port
+- **Mapping YAML** to configure which fields to sync
 
+Simply copy and run these in order to complete your integration setup.
 
 <Step3Installation />
 
diff --git a/docs/build-your-software-catalog/custom-integration/ocean-http/overview.md b/docs/build-your-software-catalog/custom-integration/ocean-http/overview.md
@@ -79,13 +79,13 @@ Where is the actual data in your API's response?
 }
 ```
 
-You'll use a JQ `data_path` in your mapping to tell the integration where to find the array of items.
+You'll use a [JQ](https://jqlang.org/manual/) `data_path` expression in your mapping to tell the integration where to find the array of items (e.g., `.data`, `.users.items`).
 
 ---
 
 ## How It Works
 
-The Generic HTTP integration uses a **two-step setup** similar to other Ocean integrations you've used:
+The Generic HTTP integration uses a [**two-step setup**](/build-your-software-catalog/sync-data-to-catalog/) similar to other Ocean integrations you've used:
 
 ### Step 1: Installation (Global Configuration)
 
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -36,6 +36,7 @@
     "docusaurus-plugin-image-zoom": "^3.0.1",
     "docusaurus-plugin-openapi-docs": "^4.5.1",
     "docusaurus-theme-openapi-docs": "^4.5.1",
+    "pluralize": "^8.0.0",
     "prettier": "^3.6.2",
     "prism-react-renderer": "^2.4.1",
     "react": "^19.2.0",
diff --git a/src/components/GenericHttp/ApiConfigBuilder.jsx b/src/components/GenericHttp/ApiConfigBuilder.jsx
@@ -207,3 +207,4 @@ export function ApiConfigBuilder() {
   );
 }
 
+
diff --git a/src/components/GenericHttp/BlueprintGenerator.jsx b/src/components/GenericHttp/BlueprintGenerator.jsx
@@ -155,3 +155,4 @@ export function BlueprintGenerator() {
   );
 }
 
+
diff --git a/src/components/GenericHttp/ConfigGenerator.jsx b/src/components/GenericHttp/ConfigGenerator.jsx
@@ -186,3 +186,4 @@ export function ConfigGenerator() {
   );
 }
 
+
diff --git a/src/components/GenericHttp/EndpointTester.jsx b/src/components/GenericHttp/EndpointTester.jsx
@@ -124,3 +124,4 @@ export function EndpointTester() {
   );
 }
 
+
diff --git a/src/components/GenericHttp/IntegrationBuilder.jsx b/src/components/GenericHttp/IntegrationBuilder.jsx
@@ -79,7 +79,7 @@ export function IntegrationBuilder() {
 
     return `docker run -d --name ocean-http-integration \\
 ${envVars.join(' \\\n')} \\
-  ghcr.io/port-labs/port-ocean-generic-http:latest`;
+  ghcr.io/port-labs/port-ocean-generic-http:0.1.5-dev`;
   };
 
   const generateHelmValues = () => {
@@ -97,30 +97,37 @@ ${envVars.join(' \\\n')} \\
       config.apiKeyHeader = apiKeyHeader;
     }
 
-    let authValue = '';
+    // Build auth config
+    let authConfig = '';
     if (authType === 'bearer_token') {
-      authValue = apiToken || '<YOUR_API_TOKEN>';
+      authConfig = `
+    apiToken: ${apiToken || '<YOUR_API_TOKEN>'}`;
     } else if (authType === 'api_key') {
-      authValue = apiKey || '<YOUR_API_KEY>';
+      authConfig = `
+    apiKey: ${apiKey || '<YOUR_API_KEY>'}`;
+      if (apiKeyHeader !== 'X-API-Key') {
+        authConfig += `
+    apiKeyHeader: ${apiKeyHeader}`;
+      }
     } else if (authType === 'basic') {
-      authValue = `${username || '<USERNAME>'}:${password || '<PASSWORD>'}`;
+      authConfig = `
+    username: ${username || '<USERNAME>'}
+    password: ${password || '<PASSWORD>'}`;
     }
 
     return `initializePortResources: true
 scheduledResyncInterval: 60
 integration:
   identifier: generic-http
   type: generic-http
+  version: 0.1.5-dev
   eventListener:
     type: POLLING
   config:
     baseUrl: ${config.baseUrl}
-    authType: ${config.authType}${config.paginationType ? `
+    authType: ${config.authType}${authConfig}${config.paginationType ? `
     paginationType: ${config.paginationType}
-    pageSize: ${config.pageSize}` : ''}${config.apiKeyHeader ? `
-    apiKeyHeader: ${config.apiKeyHeader}` : ''}${authType !== 'none' ? `
-  secrets:
-    authValue: ${authValue}` : ''}
+    pageSize: ${config.pageSize}` : ''}
 port:
   clientId: <PORT_CLIENT_ID>
   clientSecret: <PORT_CLIENT_SECRET>`;
diff --git a/src/components/GenericHttp/IntegrationBuilderSteps.jsx b/src/components/GenericHttp/IntegrationBuilderSteps.jsx
@@ -14,3 +14,4 @@ export function IntegrationBuilderSteps() {
   );
 }
 
+
diff --git a/src/components/GenericHttp/Step1ApiConfig.jsx b/src/components/GenericHttp/Step1ApiConfig.jsx
@@ -134,7 +134,7 @@ export function Step1ApiConfig() {
                     onChange={(e) => setPaginationParam(e.target.value)}
                     className={styles.input}
                   />
-                  <span className={styles.hint}>Query parameter name for pagination (e.g., "cursor", "page", "offset")</span>
+                  <span className={styles.hint}>Default: "offset" for offset, "page" for page, "cursor" for cursor</span>
                 </label>
 
                 <label className={styles.label}>
@@ -146,7 +146,7 @@ export function Step1ApiConfig() {
                     onChange={(e) => setSizeParam(e.target.value)}
                     className={styles.input}
                   />
-                  <span className={styles.hint}>Query parameter name for page size (e.g., "limit", "size", "per_page")</span>
+                  <span className={styles.hint}>Default: "limit" for offset/cursor, "size" for page</span>
                 </label>
 
                 {paginationType === 'page' && (
@@ -159,7 +159,7 @@ export function Step1ApiConfig() {
                       onChange={(e) => setStartPage(e.target.value)}
                       className={styles.input}
                     />
-                    <span className={styles.hint}>Starting page number (0 or 1, default: 1)</span>
+                    <span className={styles.hint}>Default: 1 (some APIs start at 0)</span>
                   </label>
                 )}
 
@@ -168,25 +168,25 @@ export function Step1ApiConfig() {
                     <strong>Cursor Path</strong>
                     <input
                       type="text"
-                      placeholder="meta.after_cursor, links.next"
+                      placeholder="meta.after_cursor, pagination.next_cursor"
                       value={cursorPath}
                       onChange={(e) => setCursorPath(e.target.value)}
                       className={styles.input}
                     />
-                    <span className={styles.hint}>Dot-notation path to extract cursor from response (e.g., "meta.after_cursor")</span>
+                    <span className={styles.hint}>Dot-notation path to extract cursor from response (e.g., "meta.after_cursor", "links.next")</span>
                   </label>
                 )}
 
                 <label className={styles.label}>
                   <strong>Has More Path</strong>
                   <input
                     type="text"
-                    placeholder="meta.has_more, pagination.hasMore"
+                    placeholder="pagination.has_more, meta.hasMore"
                     value={hasMorePath}
                     onChange={(e) => setHasMorePath(e.target.value)}
                     className={styles.input}
                   />
-                  <span className={styles.hint}>Dot-notation path to check if more pages exist (e.g., "meta.has_more")</span>
+                  <span className={styles.hint}>Dot-notation path to check if more pages exist (e.g., "pagination.has_more", "meta.hasMore")</span>
                 </label>
               </>
             )}
diff --git a/src/components/GenericHttp/Step2DataMapping.jsx b/src/components/GenericHttp/Step2DataMapping.jsx
@@ -1,4 +1,5 @@
-import React from 'react';
+import React, { useEffect } from 'react';
+import pluralize from 'pluralize';
 import { useIntegrationBuilder } from './IntegrationBuilderContext';
 import styles from './styles.module.css';
 
@@ -14,6 +15,61 @@ export function Step2DataMapping() {
     titleField, setTitleField,
   } = useIntegrationBuilder();
 
+  // Auto-generate blueprint ID and title from endpoint path
+  useEffect(() => {
+    if (endpoint) {
+      // Extract last meaningful segment from path (e.g., /api/v1/users -> users)
+      const segments = endpoint.split('/').filter(s => s && !s.match(/^(api|v\d+)$/i));
+      const lastSegment = segments[segments.length - 1] || 'resource';
+      // Convert to singular using pluralize library (handles edge cases like companies -> company)
+      const singular = pluralize.singular(lastSegment);
+      const generatedId = singular.toLowerCase().replace(/[^a-z0-9]/g, '_');
+      
+      // Generate title with capital first letter
+      const generatedTitle = singular.charAt(0).toUpperCase() + singular.slice(1).toLowerCase();
+      
+      setBlueprintId(generatedId);
+      setBlueprintTitle(generatedTitle);
+    }
+  }, [endpoint, setBlueprintId, setBlueprintTitle]);
+
+  // Auto-select first array when JSON is pasted
+  useEffect(() => {
+    if (responseJson && dataPath === null) {
+      try {
+        const json = JSON.parse(responseJson);
+        
+        // Check if root is an array
+        if (Array.isArray(json)) {
+          setDataPath('');
+          return;
+        }
+        
+        // Find first array in the object
+        const findFirstArray = (obj, path = '') => {
+          for (const [key, value] of Object.entries(obj)) {
+            const currentPath = path ? `${path}.${key}` : `.${key}`;
+            if (Array.isArray(value)) {
+              return currentPath;
+            }
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+              const found = findFirstArray(value, currentPath);
+              if (found) return found;
+            }
+          }
+          return null;
+        };
+        
+        const firstArrayPath = findFirstArray(json);
+        if (firstArrayPath) {
+          setDataPath(firstArrayPath);
+        }
+      } catch {
+        // Invalid JSON, do nothing
+      }
+    }
+  }, [responseJson, dataPath, setDataPath]);
+
   const parseFields = () => {
     if (dataPath === null || !responseJson) {
       return [];
@@ -244,8 +300,12 @@ export function Step2DataMapping() {
                           <button
                             className={`${styles.roleButton} ${identifierField === field.key ? styles.active : ''}`}
                             onClick={() => {
-                              setIdentifierField(field.key);
-                              setSelectedFields(prev => ({ ...prev, [field.key]: true }));
+                              if (identifierField === field.key) {
+                                setIdentifierField('');
+                              } else {
+                                setIdentifierField(field.key);
+                                setSelectedFields(prev => ({ ...prev, [field.key]: true }));
+                              }
                             }}
                             title="Use as unique identifier (required)"
                           >
@@ -254,8 +314,12 @@ export function Step2DataMapping() {
                           <button
                             className={`${styles.roleButton} ${titleField === field.key ? styles.active : ''}`}
                             onClick={() => {
-                              setTitleField(field.key);
-                              setSelectedFields(prev => ({ ...prev, [field.key]: true }));
+                              if (titleField === field.key) {
+                                setTitleField('');
+                              } else {
+                                setTitleField(field.key);
+                                setSelectedFields(prev => ({ ...prev, [field.key]: true }));
+                              }
                             }}
                             title="Use as display title (optional)"
                           >
diff --git a/src/components/GenericHttp/Step3Installation.jsx b/src/components/GenericHttp/Step3Installation.jsx

Original file line number	Diff line number	Diff line change
`@@ -207,3 +207,4 @@ export function ApiConfigBuilder() {`
`207`	`207`	`);`
`208`	`208`	`}`
`209`	`209`
	`210`	`+`
Original file line number	Diff line number	Diff line change
`@@ -155,3 +155,4 @@ export function BlueprintGenerator() {`
`155`	`155`	`);`
`156`	`156`	`}`
`157`	`157`
	`158`	`+`
Original file line number	Diff line number	Diff line change
`@@ -186,3 +186,4 @@ export function ConfigGenerator() {`
`186`	`186`	`);`
`187`	`187`	`}`
`188`	`188`
	`189`	`+`
Original file line number	Diff line number	Diff line change
`@@ -124,3 +124,4 @@ export function EndpointTester() {`
`124`	`124`	`);`
`125`	`125`	`}`
`126`	`126`
	`127`	`+`
Original file line number	Diff line number	Diff line change
`@@ -14,3 +14,4 @@ export function IntegrationBuilderSteps() {`
`14`	`14`	`);`
`15`	`15`	`}`
`16`	`16`
	`17`	`+`