docs: document replace and upsert serializer actions for the upload API

[Copilot]

The upload API documentation was missing coverage of the replace and upsert actions exposed by OverwriteImporterSerializer and UpsertImporterSerializer, and the "Overwriting a dataset" section referenced a non-existent overwrite_existing_layer parameter.

Changes

• "Overwriting a dataset": Replace the incorrect overwrite_existing_layer description with the actual action=replace + resource_pk fields, including Python and cURL examples.
• "Upserting dataset features" (new section): Document action=upsert with resource_pk and upsert_key (defaults to fid), explaining the insert-or-update semantics, with Python and cURL examples.
• "Skip existing dataset": Fix typos and add a complete code example for skip_existing_layers=True.

Replace example

data = {
    'action': 'replace',
    'resource_pk': 1,  # primary key of the dataset to replace
}
response = requests.post(url, headers=headers, data=data, files=files)

Upsert example

data = {
    'action': 'upsert',
    'resource_pk': 1,      # primary key of the target dataset
    'upsert_key': 'fid',   # field used to match existing features; defaults to 'fid'
}
response = requests.post(url, headers=headers, data=data, files=files)

Original prompt

did you look at the different actions from the serializer ? There are more action

[Chronological Review: The conversation began with the user requesting a review and enhancement of the API usage documentation for GeoNode, specifically focusing on various sections related to datasets and metadata. The user then inquired about the different actions from the serializer, indicating a need for deeper exploration of the API's capabilities. The user subsequently canceled a command to delegate tasks to a cloud agent, suggesting a desire to maintain control over the documentation process.]

[Intent Mapping:

• "Review and enhance API usage docs for GeoNode [Backport to 2.10.x][Fixes #5849] Read Only and Maintenance modes #5989" - The user aims to update and improve the API documentation, focusing on specific sections and adding missing documentation.
• "did you look at the different actions from the serializer?" - The user is seeking clarification on the serializer's capabilities and wants to ensure all actions are considered in the documentation.]

[Technical Inventory:

• Technologies: GeoNode API, OpenAPI documentation.
• Frameworks: Django REST Framework (implied by the mention of serializers).
• Architectural Decisions: Maintaining a curated manual documentation alongside automated OpenAPI generation.]

[Code Archaeology:

• File: /home/niraj/GeoSolutions/geonode/geonode/upload/api/views.py - This file is central to the API's functionality and is where the user is currently focused.
• Functions/Classes: Specific actions related to dataset uploads and metadata handling were discussed, but no specific code changes were documented in this conversation.]

[Progress Assessment:

• Completed Tasks: The user has outlined the sections to be reviewed and updated in the API documentation.
• Partially Complete Work: The user is in the process of reviewing the serializer actions and enhancing the documentation.]

[Context Validation: All critical information regarding the user's goals for enhancing the API documentation and the specific sections to be updated is captured.]

[Recent Commands Analysis:

• Last Agent Commands: The user asked about the different actions from the serializer, indicating a need for further exploration of the API's capabilities.
• Tool Results Summary: No specific tool results were returned as the conversation focused on user inquiries rather than tool executions.
• Pre-Summary State: The agent was actively discussing the serializer actions and their relevance to the API documentation when the token budget was exceeded.
• Operation Context: The user's inquiries about the serializer actions are directly related to their goal of ensuring comprehensive documentation for the GeoNode API.]

1. Conversation Overview: - Primary Objectives: "Review and enhance API usage docs for GeoNode #5989" and "did you look at the different actions from the serializer?" - Session Context: The user is focused on improving the API documentation for GeoNode, specifically targeting sections related to datasets and metadata, while also exploring the capabilities of the serializer. - User Intent Evolution: The user started with a clear request for documentation enhancement and then sought clarification on the serializer's actions, indicating a deeper engagement with the API's functionality.

2. Technical Foundation:

• GeoNode API: The API being documented, which has limitations in its current OpenAPI generation.
• Django REST Framework: Implied usage for handling API serialization.

3. Codebase Status:

• File Name: /home/niraj/GeoSolutions/geonode/geonode/upload/api/views.py
• Purpose: This file is crucial for defining the API views and handling dataset uploads.
• Current State: The user is currently reviewing the file to enhance API documentation.
• Key Code Segments: Specific actions related to dataset uploads and metadata handling were mentioned but not detailed.
• Dependencies: This file interacts with the overall API structure and documentation efforts.

4. Problem Resolution:

• Issues Encountered: The user is addressing the limitations of the current API documentation and serializer actions.
• Solutions Implemented: The user is actively working on reviewing and enhancing the documentation.
• Debugging Context: No specific debugging efforts were mentioned, but the user is clarifying the serializer's capabilities.
• Lessons Learned: The need for comprehensive documentation and understanding of the API's actions.

5. Progress Tracking:

• Completed Tasks: The user has identified sections for documentation enhancement.
• Partially Complete Work: The user is in the process of reviewing serializer actions.
• Validated Outcomes: No specific outcomes have been validated yet.

6. Active Work State:

• Current Focus: The user is reviewing the actions from the serializer to ensure all are documented.
• Recent Context: The user has been discussing the need for a thorough understanding of the serializer's actions.
• Working Code: The user is focused on the fil...

Created from VS Code.

[cla-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have the users @Copilot on file. In order for us to review and merge your code, please contact the project maintainers to get yourself added.

[cla-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have the users @Copilot on file. In order for us to review and merge your code, please contact the project maintainers to get yourself added.