Merge pull request #3 from hubuum/codex/update-relationship-query-model-for-classes

Align relationship model with class related endpoints

Author: terjekv

CHANGELOG.md

@@ -9,10 +9,13 @@ The format is based on Keep a Changelog, and this project aims to follow Semanti
 ### Changed
 
 - Redesigned relationship helpers around the new relation endpoint layout:
+  - `Class::related_classes()` now targets `/api/v1/classes/{class_id}/related/classes`
+  - added `Class::related_relations()` for `/api/v1/classes/{class_id}/related/relations`
+  - added `Class::related_graph()` for `/api/v1/classes/{class_id}/related/graph`
   - `Object::related_objects()` now targets `/api/v1/classes/{class_id}/objects/{object_id}/related/objects`
   - added `Object::related_relations()` for `/related/relations`
   - added `Object::related_graph()` for `/related/graph`
-- Cursor-backed relationship requests now support query filters in addition to sorting, limits, and cursors, so class-transitive, class-scoped, related-object, and related-relation listings can all use the shared DB query interface.
+- Cursor-backed relationship requests now support query filters in addition to sorting, limits, and cursors, so connected-class, class-related-relation, related-object, and related-relation listings can all use the shared DB query interface.
 - `Client::search(...)` is now the typed unified search builder for `/api/v1/search` and `/api/v1/search/stream`.
 
 ### Added
@@ -23,6 +26,7 @@ The format is based on Keep a Changelog, and this project aims to follow Semanti
 ### Breaking
 
 - The public `Client::search`/`AsyncClient::search` low-level resource helper has been replaced by the unified search builder. Resource querying continues through resource handles like `client.classes().query()`.
+- `Class::transitive_relations()` and `Class::transitive_relations_to(...)` were removed. Class traversal now mirrors object traversal through `related_classes()`, `related_relations()`, and `related_graph()`.
 - Relationship examples and fluent filters should use the new API query aliases such as `from_classes`, `to_classes`, `from_objects`, `to_objects`, and `class_relation` instead of the older storage-shaped field names.
 
 ## [0.0.1] - 2026-03-12

Cargo.lock

@@ -210,12 +210,12 @@ mod parity_contract {
             let _ = $module::Handle::<Class>::delete;
             let _ = $module::Handle::<Class>::permissions;
             let _ = $module::Handle::<Class>::permissions_request;
-            let _ = $module::Handle::<Class>::relations;
+            let _ = $module::Handle::<Class>::related_classes;
+            let _ = $module::Handle::<Class>::related_relations;
+            let _ = $module::Handle::<Class>::related_graph;
             let _ = $module::Handle::<Class>::relation;
             let _ = $module::Handle::<Class>::create_relation;
             let _ = $module::Handle::<Class>::delete_relation;
-            let _ = $module::Handle::<Class>::transitive_relations;
-            let _ = $module::Handle::<Class>::transitive_relations_to;
 
             let _ = $module::Handle::<Object>::related_objects;
             let _ = $module::Handle::<Object>::related_relations;

src/client/mod.rs

@@ -21,10 +21,11 @@ pub enum Endpoint {
     Classes,
     ClassesById,
     ClassPermissions,
-    ClassScopedRelations,
-    ClassScopedRelationById,
-    ClassRelationsTransitive,
-    ClassRelationsTransitiveTo,
+    ClassRelatedClasses,
+    ClassRelatedRelations,
+    ClassRelatedGraph,
+    ClassRelationsFromClass,
+    ClassRelationFromClassById,
     Namespaces,
     NamespacesById,
     NamespacePermissions,
@@ -78,16 +79,13 @@ impl Endpoint {
             Endpoint::Classes => "/api/v1/classes",
             Endpoint::ClassesById => "/api/v1/classes/{class_id}",
             Endpoint::ClassPermissions => "/api/v1/classes/{class_id}/permissions",
-            Endpoint::ClassScopedRelations => "/api/v1/classes/{class_id}/relations",
-            Endpoint::ClassScopedRelationById => {
+            Endpoint::ClassRelatedClasses => "/api/v1/classes/{class_id}/related/classes",
+            Endpoint::ClassRelatedRelations => "/api/v1/classes/{class_id}/related/relations",
+            Endpoint::ClassRelatedGraph => "/api/v1/classes/{class_id}/related/graph",
+            Endpoint::ClassRelationsFromClass => "/api/v1/classes/{class_id}/relations",
+            Endpoint::ClassRelationFromClassById => {
                 "/api/v1/classes/{class_id}/relations/{relation_id}"
             }
-            Endpoint::ClassRelationsTransitive => {
-                "/api/v1/classes/{class_id}/relations/transitive/"
-            }
-            Endpoint::ClassRelationsTransitiveTo => {
-                "/api/v1/classes/{class_id}/relations/transitive/class/{class_id_to}"
-            }
             Endpoint::Namespaces => "/api/v1/namespaces",
             Endpoint::NamespacesById => "/api/v1/namespaces/{namespace_id}",
 
@@ -172,10 +170,11 @@ mod test {
         get_group_by_id = { Endpoint::GroupsById, "/api/v1/iam/groups/{group_id}" },
         get_class_permissions = { Endpoint::ClassPermissions, "/api/v1/classes/{class_id}/permissions" },
         get_class_by_id = { Endpoint::ClassesById, "/api/v1/classes/{class_id}" },
-        get_class_scoped_relations = { Endpoint::ClassScopedRelations, "/api/v1/classes/{class_id}/relations" },
-        get_class_scoped_relation_by_id = { Endpoint::ClassScopedRelationById, "/api/v1/classes/{class_id}/relations/{relation_id}" },
-        get_class_transitive = { Endpoint::ClassRelationsTransitive, "/api/v1/classes/{class_id}/relations/transitive/" },
-        get_class_transitive_to = { Endpoint::ClassRelationsTransitiveTo, "/api/v1/classes/{class_id}/relations/transitive/class/{class_id_to}" },
+        get_class_related_classes = { Endpoint::ClassRelatedClasses, "/api/v1/classes/{class_id}/related/classes" },
+        get_class_related_relations = { Endpoint::ClassRelatedRelations, "/api/v1/classes/{class_id}/related/relations" },
+        get_class_related_graph = { Endpoint::ClassRelatedGraph, "/api/v1/classes/{class_id}/related/graph" },
+        class_relations_from_class = { Endpoint::ClassRelationsFromClass, "/api/v1/classes/{class_id}/relations" },
+        class_relation_from_class_by_id = { Endpoint::ClassRelationFromClassById, "/api/v1/classes/{class_id}/relations/{relation_id}" },
         get_namespace_by_id = { Endpoint::NamespacesById, "/api/v1/namespaces/{namespace_id}" },
         get_namespace_permission_grant = { Endpoint::NamespacePermissionsGrant, "/api/v1/namespaces/{namespace_id}/permissions/group/{group_id}" },
         get_namespace_single_permission_grant = { Endpoint::NamespacePermissionGrant, "/api/v1/namespaces/{namespace_id}/permissions/group/{group_id}/{permission}" },
@@ -220,10 +219,11 @@ mod test {
         get_group_by_id = { Endpoint::GroupsById, '/', "api/v1/iam/groups/{group_id}" },
         get_class_permissions = { Endpoint::ClassPermissions, '/', "api/v1/classes/{class_id}/permissions" },
         get_class_by_id = { Endpoint::ClassesById, '/', "api/v1/classes/{class_id}" },
-        get_class_scoped_relations = { Endpoint::ClassScopedRelations, '/', "api/v1/classes/{class_id}/relations" },
-        get_class_scoped_relation_by_id = { Endpoint::ClassScopedRelationById, '/', "api/v1/classes/{class_id}/relations/{relation_id}" },
-        get_class_transitive = { Endpoint::ClassRelationsTransitive, '/', "api/v1/classes/{class_id}/relations/transitive/" },
-        get_class_transitive_to = { Endpoint::ClassRelationsTransitiveTo, '/', "api/v1/classes/{class_id}/relations/transitive/class/{class_id_to}" },
+        get_class_related_classes = { Endpoint::ClassRelatedClasses, '/', "api/v1/classes/{class_id}/related/classes" },
+        get_class_related_relations = { Endpoint::ClassRelatedRelations, '/', "api/v1/classes/{class_id}/related/relations" },
+        get_class_related_graph = { Endpoint::ClassRelatedGraph, '/', "api/v1/classes/{class_id}/related/graph" },
+        class_relations_from_class = { Endpoint::ClassRelationsFromClass, '/', "api/v1/classes/{class_id}/relations" },
+        class_relation_from_class_by_id = { Endpoint::ClassRelationFromClassById, '/', "api/v1/classes/{class_id}/relations/{relation_id}" },
         get_namespace_by_id = { Endpoint::NamespacesById, '/', "api/v1/namespaces/{namespace_id}" },
         get_namespace_permission_grant = { Endpoint::NamespacePermissionsGrant, '/', "api/v1/namespaces/{namespace_id}/permissions/group/{group_id}" },
         get_namespace_single_permission_grant = { Endpoint::NamespacePermissionGrant, '/', "api/v1/namespaces/{namespace_id}/permissions/group/{group_id}/{permission}" },

src/endpoints.rs

@@ -7,11 +7,12 @@ use crate::{
     client::{
         r#async::{
             CursorRequest as AsyncCursorRequest, EmptyPostParams as AsyncEmptyPostParams,
-            Handle as AsyncHandle, QueryOp as AsyncQueryOp,
+            GraphRequest as AsyncGraphRequest, Handle as AsyncHandle, QueryOp as AsyncQueryOp,
         },
         sync::{
             CursorRequest as SyncCursorRequest, EmptyPostParams as SyncEmptyPostParams,
-            Handle as SyncHandle, QueryOp as SyncQueryOp, one_or_err,
+            GraphRequest as SyncGraphRequest, Handle as SyncHandle, QueryOp as SyncQueryOp,
+            one_or_err,
         },
     },
     endpoints::Endpoint,
@@ -58,11 +59,22 @@ pub struct ClassRelationResource {
 }
 
 #[derive(Default, Debug, serde::Serialize, serde::Deserialize, Clone, PartialEq)]
-pub struct ClassRelationTransitive {
-    pub ancestor_class_id: i32,
-    pub descendant_class_id: i32,
-    pub depth: i32,
-    pub path: Vec<Option<i32>>,
+pub struct ClassWithPath {
+    pub id: i32,
+    pub name: String,
+    pub namespace_id: i32,
+    pub description: String,
+    pub json_schema: serde_json::Value,
+    pub validate_schema: bool,
+    pub created_at: HubuumDateTime,
+    pub updated_at: HubuumDateTime,
+    pub path: Vec<i32>,
+}
+
+#[derive(Default, Debug, serde::Serialize, serde::Deserialize, Clone, PartialEq)]
+pub struct RelatedClassGraph {
+    pub classes: Vec<ClassWithPath>,
+    pub relations: Vec<ClassRelation>,
 }
 
 impl SyncHandle<Class> {
@@ -135,10 +147,26 @@ impl SyncHandle<Class> {
         )
     }
 
-    pub fn relations(&self) -> SyncCursorRequest<ClassRelation> {
+    pub fn related_classes(&self) -> SyncCursorRequest<ClassWithPath> {
         SyncCursorRequest::new(
             self.client().clone(),
-            Endpoint::ClassScopedRelations,
+            Endpoint::ClassRelatedClasses,
+            vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
+        )
+    }
+
+    pub fn related_relations(&self) -> SyncCursorRequest<ClassRelation> {
+        SyncCursorRequest::new(
+            self.client().clone(),
+            Endpoint::ClassRelatedRelations,
+            vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
+        )
+    }
+
+    pub fn related_graph(&self) -> SyncGraphRequest<RelatedClassGraph> {
+        SyncGraphRequest::new(
+            self.client().clone(),
+            Endpoint::ClassRelatedGraph,
             vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
         )
     }
@@ -164,7 +192,7 @@ impl SyncHandle<Class> {
         self.client()
             .request_with_endpoint::<NewClassRelationFromClassParams, ClassRelation>(
                 reqwest::Method::POST,
-                &Endpoint::ClassScopedRelations,
+                &Endpoint::ClassRelationsFromClass,
                 vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
                 vec![],
                 NewClassRelationFromClassParams {
@@ -180,7 +208,7 @@ impl SyncHandle<Class> {
         self.client()
             .request_with_endpoint::<SyncEmptyPostParams, ()>(
                 reqwest::Method::DELETE,
-                &Endpoint::ClassScopedRelationById,
+                &Endpoint::ClassRelationFromClassById,
                 vec![
                     (Cow::Borrowed("class_id"), self.id().to_string().into()),
                     (Cow::Borrowed("relation_id"), relation_id.to_string().into()),
@@ -190,28 +218,6 @@ impl SyncHandle<Class> {
             )?;
         Ok(())
     }
-
-    pub fn transitive_relations(&self) -> SyncCursorRequest<ClassRelationTransitive> {
-        SyncCursorRequest::new(
-            self.client().clone(),
-            Endpoint::ClassRelationsTransitive,
-            vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
-        )
-    }
-
-    pub fn transitive_relations_to(
-        &self,
-        class_id: i32,
-    ) -> SyncCursorRequest<ClassRelationTransitive> {
-        SyncCursorRequest::new(
-            self.client().clone(),
-            Endpoint::ClassRelationsTransitiveTo,
-            vec![
-                (Cow::Borrowed("class_id"), self.id().to_string().into()),
-                (Cow::Borrowed("class_id_to"), class_id.to_string().into()),
-            ],
-        )
-    }
 }
 
 impl AsyncHandle<Class> {
@@ -266,10 +272,26 @@ impl AsyncHandle<Class> {
         )
     }
 
-    pub fn relations(&self) -> AsyncCursorRequest<ClassRelation> {
+    pub fn related_classes(&self) -> AsyncCursorRequest<ClassWithPath> {
+        AsyncCursorRequest::new(
+            self.client().clone(),
+            Endpoint::ClassRelatedClasses,
+            vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
+        )
+    }
+
+    pub fn related_relations(&self) -> AsyncCursorRequest<ClassRelation> {
         AsyncCursorRequest::new(
             self.client().clone(),
-            Endpoint::ClassScopedRelations,
+            Endpoint::ClassRelatedRelations,
+            vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
+        )
+    }
+
+    pub fn related_graph(&self) -> AsyncGraphRequest<RelatedClassGraph> {
+        AsyncGraphRequest::new(
+            self.client().clone(),
+            Endpoint::ClassRelatedGraph,
             vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
         )
     }
@@ -296,7 +318,7 @@ impl AsyncHandle<Class> {
         self.client()
             .request_with_endpoint::<NewClassRelationFromClassParams, ClassRelation>(
                 reqwest::Method::POST,
-                &Endpoint::ClassScopedRelations,
+                &Endpoint::ClassRelationsFromClass,
                 vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
                 vec![],
                 NewClassRelationFromClassParams {
@@ -313,7 +335,7 @@ impl AsyncHandle<Class> {
         self.client()
             .request_with_endpoint::<AsyncEmptyPostParams, ()>(
                 reqwest::Method::DELETE,
-                &Endpoint::ClassScopedRelationById,
+                &Endpoint::ClassRelationFromClassById,
                 vec![
                     (Cow::Borrowed("class_id"), self.id().to_string().into()),
                     (Cow::Borrowed("relation_id"), relation_id.to_string().into()),
@@ -324,26 +346,4 @@ impl AsyncHandle<Class> {
             .await?;
         Ok(())
     }
-
-    pub fn transitive_relations(&self) -> AsyncCursorRequest<ClassRelationTransitive> {
-        AsyncCursorRequest::new(
-            self.client().clone(),
-            Endpoint::ClassRelationsTransitive,
-            vec![(Cow::Borrowed("class_id"), self.id().to_string().into())],
-        )
-    }
-
-    pub fn transitive_relations_to(
-        &self,
-        class_id: i32,
-    ) -> AsyncCursorRequest<ClassRelationTransitive> {
-        AsyncCursorRequest::new(
-            self.client().clone(),
-            Endpoint::ClassRelationsTransitiveTo,
-            vec![
-                (Cow::Borrowed("class_id"), self.id().to_string().into()),
-                (Cow::Borrowed("class_id_to"), class_id.to_string().into()),
-            ],
-        )
-    }
 }

src/resources/class.rs

@@ -11,7 +11,7 @@ mod user;
 
 pub use self::class::{
     Class, ClassGet, ClassPatch, ClassPost, ClassRelation, ClassRelationGet, ClassRelationPatch,
-    ClassRelationPost, ClassRelationTransitive,
+    ClassRelationPost, ClassWithPath, RelatedClassGraph,
 };
 pub use self::group::{Group, GroupGet, GroupPatch, GroupPost};
 pub use self::namespace::{Namespace, NamespaceGet, NamespacePatch, NamespacePost};