From 59b306be6941db634d2f8251fbc6dd70074e79a0 Mon Sep 17 00:00:00 2001
From: Mondo Diaz <armando.m.diaz@boeing.com>
Date: Fri, 12 Dec 2025 09:47:58 -0600
Subject: [PATCH] Update README with new tag and artifact API endpoints

- Document enhanced tags listing with pagination, search, sort
- Add examples for single tag and tag history endpoints
- Add examples for listing artifacts by package with filtering
- Update artifact endpoint to show tag references in response
---
 README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 112 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 8abe1db..ba48e11 100644
--- a/README.md
+++ b/README.md
@@ -56,10 +56,13 @@ Orchard is a centralized binary artifact storage system that provides content-ad
 | `POST` | `/api/v1/project/:project/:package/upload` | Upload an artifact |
 | `GET` | `/api/v1/project/:project/:package/+/:ref` | Download an artifact (supports Range header) |
 | `HEAD` | `/api/v1/project/:project/:package/+/:ref` | Get artifact metadata without downloading |
-| `GET` | `/api/v1/project/:project/:package/tags` | List all tags |
+| `GET` | `/api/v1/project/:project/:package/tags` | List tags (with pagination, search, sorting, artifact metadata) |
 | `POST` | `/api/v1/project/:project/:package/tags` | Create a tag |
+| `GET` | `/api/v1/project/:project/:package/tags/:tag_name` | Get single tag with artifact metadata |
+| `GET` | `/api/v1/project/:project/:package/tags/:tag_name/history` | Get tag change history |
+| `GET` | `/api/v1/project/:project/:package/artifacts` | List artifacts in package (with filtering) |
 | `GET` | `/api/v1/project/:project/:package/consumers` | List consumers of a package |
-| `GET` | `/api/v1/artifact/:id` | Get artifact metadata by hash |
+| `GET` | `/api/v1/artifact/:id` | Get artifact metadata with referencing tags |
 
 #### Resumable Upload Endpoints
 
@@ -290,12 +293,119 @@ curl -X POST http://localhost:8080/api/v1/project/my-project/releases/tags \
   -d '{"name": "stable", "artifact_id": "a3f5d8e12b4c6789..."}'
 ```
 
+### List Tags
+
+```bash
+# Basic listing with artifact metadata
+curl http://localhost:8080/api/v1/project/my-project/releases/tags
+
+# With pagination
+curl "http://localhost:8080/api/v1/project/my-project/releases/tags?page=1&limit=10"
+
+# Search by tag name
+curl "http://localhost:8080/api/v1/project/my-project/releases/tags?search=v1"
+
+# Sort by created_at descending
+curl "http://localhost:8080/api/v1/project/my-project/releases/tags?sort=created_at&order=desc"
+```
+
+Response includes artifact metadata:
+```json
+{
+  "items": [
+    {
+      "id": "uuid",
+      "package_id": "uuid",
+      "name": "v1.0.0",
+      "artifact_id": "a3f5d8e...",
+      "created_at": "2025-01-01T00:00:00Z",
+      "created_by": "user",
+      "artifact_size": 1048576,
+      "artifact_content_type": "application/gzip",
+      "artifact_original_name": "app-v1.0.0.tar.gz",
+      "artifact_created_at": "2025-01-01T00:00:00Z",
+      "artifact_format_metadata": {}
+    }
+  ],
+  "pagination": {"page": 1, "limit": 20, "total": 1, "total_pages": 1}
+}
+```
+
+### Get Single Tag
+
+```bash
+curl http://localhost:8080/api/v1/project/my-project/releases/tags/v1.0.0
+```
+
+### Get Tag History
+
+```bash
+curl http://localhost:8080/api/v1/project/my-project/releases/tags/latest/history
+```
+
+Returns list of artifact changes for the tag (most recent first).
+
+### List Artifacts in Package
+
+```bash
+# Basic listing
+curl http://localhost:8080/api/v1/project/my-project/releases/artifacts
+
+# Filter by content type
+curl "http://localhost:8080/api/v1/project/my-project/releases/artifacts?content_type=application/gzip"
+
+# Filter by date range
+curl "http://localhost:8080/api/v1/project/my-project/releases/artifacts?created_after=2025-01-01T00:00:00Z"
+```
+
+Response includes tags pointing to each artifact:
+```json
+{
+  "items": [
+    {
+      "id": "a3f5d8e...",
+      "size": 1048576,
+      "content_type": "application/gzip",
+      "original_name": "app-v1.0.0.tar.gz",
+      "created_at": "2025-01-01T00:00:00Z",
+      "created_by": "user",
+      "format_metadata": {},
+      "tags": ["v1.0.0", "latest", "stable"]
+    }
+  ],
+  "pagination": {"page": 1, "limit": 20, "total": 1, "total_pages": 1}
+}
+```
+
 ### Get Artifact by ID
 
 ```bash
 curl http://localhost:8080/api/v1/artifact/a3f5d8e12b4c67890abcdef1234567890abcdef1234567890abcdef12345678
 ```
 
+Response includes all tags/packages referencing the artifact:
+```json
+{
+  "id": "a3f5d8e...",
+  "size": 1048576,
+  "content_type": "application/gzip",
+  "original_name": "app-v1.0.0.tar.gz",
+  "created_at": "2025-01-01T00:00:00Z",
+  "created_by": "user",
+  "ref_count": 2,
+  "format_metadata": {},
+  "tags": [
+    {
+      "id": "uuid",
+      "name": "v1.0.0",
+      "package_id": "uuid",
+      "package_name": "releases",
+      "project_name": "my-project"
+    }
+  ]
+}
+```
+
 ## Project Structure
 
 ```