[docs] Expand and update File Import API documentation

[Harshg999]

What changes were proposed in this pull request?

• Provides a comprehensive, step-by-step guide for the File Import API, detailing endpoints, parameters, example requests, and responses.
• Clarifies the import workflow and adds documentation for features like metadata detection, header guessing, previewing, and SQL type mapping.
• Improves clarity and usefulness for developers integrating file import functionality.

How was this patch tested?

• Manually

[Copilot]

Pull Request Overview

This PR updates and expands the documentation for the File Import API, providing a comprehensive guide with detailed endpoint descriptions, request parameters, examples, and a complete workflow for importing files.

• Expanded overview and introduction for the API
• Detailed endpoint documentation with request/response examples and parameter tables
• A complete workflow example consolidating multiple API calls

Comments suppressed due to low confidence (1)

docs/docs-site/content/developer/api/rest/_index.md:575

• [nitpick] Consider using a more descriptive heading (e.g., 'File Importer') instead of the generic 'Importer' to align with the API naming in the endpoints.

## Importer

[github-actions]

⚠️ No test files modified. Please ensure that changes are properly tested. ⚠️

[ramprasadagarwal]

Great Documentation.

[github-actions]

Python Coverage Report •

File	Stmts	Miss	Cover	Missing
TOTAL	54185	27078	50%

report-only-changed-files is enabled. No files were changed during this commit :)

Pytest Report

Tests	Skipped	Failures	Errors	Time
1186	106 💤	0 ❌	0 🔥	5m 54s ⏱️

[bjornalm]

Nice, we should let someone try it all out using this manual? Perhaps let an AI have a go and see if the docs is enough for it to get it right?

[bjornalm]

From Gemini

Blind Spots or Unclear Aspects:

Handling of delimiter_format for file_type: In the Guess File Header and Preview File endpoints, file_type can be delimiter_format. However, the documentation doesn't explicitly describe what "delimiter_format" entails or how it might differ from csv or tsv in terms of required parameters (e.g., if field_separator is mandatory).

record_separator in preview endpoint: The preview endpoint has record_separator as an optional parameter with a default of \n. While field_separator and quote_char are clearly derived from guess_metadata for CSV/TSV, it's not explicitly stated if record_separator also comes from guess_metadata or if it's always assumed to be \n. The guess_metadata response for CSV/TSV does include record_separator, so it would be good to explicitly state that it should be passed to preview if desired.

[Harshg999]

From Gemini

Blind Spots or Unclear Aspects:

Handling of delimiter_format for file_type: In the Guess File Header and Preview File endpoints, file_type can be delimiter_format. However, the documentation doesn't explicitly describe what "delimiter_format" entails or how it might differ from csv or tsv in terms of required parameters (e.g., if field_separator is mandatory).

record_separator in preview endpoint: The preview endpoint has record_separator as an optional parameter with a default of \n. While field_separator and quote_char are clearly derived from guess_metadata for CSV/TSV, it's not explicitly stated if record_separator also comes from guess_metadata or if it's always assumed to be \n. The guess_metadata response for CSV/TSV does include record_separator, so it would be good to explicitly state that it should be passed to preview if desired.

Added required changes.