From f5870594689babc492b3ca5b93b9edbc86f97b4b Mon Sep 17 00:00:00 2001 From: phil Date: Fri, 3 Oct 2025 13:38:43 -0400 Subject: [PATCH] api docs for many-to-many counts --- constellation/src/server/filters.rs | 4 ++ .../templates/get-many-to-many-counts.html.j2 | 55 ++++++++++++++++++- constellation/templates/hello.html.j2 | 26 +++++++++ constellation/templates/try-it-macros.html.j2 | 44 ++++++++++++++- 4 files changed, 126 insertions(+), 3 deletions(-) diff --git a/constellation/src/server/filters.rs b/constellation/src/server/filters.rs index 9339a50..d8ab57f 100644 --- a/constellation/src/server/filters.rs +++ b/constellation/src/server/filters.rs @@ -22,3 +22,7 @@ pub fn to_browseable(s: &str) -> askama::Result> { pub fn human_number(n: &u64) -> askama::Result { Ok(n.to_formatted_string(&Locale::en)) } + +pub fn to_u64(n: usize) -> askama::Result { + Ok(n as u64) +} diff --git a/constellation/templates/get-many-to-many-counts.html.j2 b/constellation/templates/get-many-to-many-counts.html.j2 index b0aa16d..b27815c 100644 --- a/constellation/templates/get-many-to-many-counts.html.j2 +++ b/constellation/templates/get-many-to-many-counts.html.j2 @@ -2,11 +2,62 @@ {% import "try-it-macros.html.j2" as try_it %} {% block title %}Many to Many counts{% endblock %} -{% block description %}All {{ query.source }} records with links to {{ query.subject }}{% endblock %} +{% block description %}Counts of many-to-many {{ query.source }} join records with links to {{ query.subject }} and a secondary target at {{ query.path_to_other }}{% endblock %} {% block content %} - (todo) + {% call try_it::get_many_to_many_counts( + query.subject, + query.source, + query.path_to_other, + query.did, + query.other_subject, + query.limit, + ) %} + +

+ Many-to-many links to {{ query.subject }} joining through {{ query.path_to_other }} + {% if let Some(browseable_uri) = query.subject|to_browseable %} + browse record + {% endif %} +

+ +

{% if cursor.is_some() || query.cursor.is_some() %}more than {% endif %}{{ counts_by_other_subject.len()|to_u64|human_number }} joins {{ query.source }}→{{ query.path_to_other }}

+ + + +

Counts by other subject:

+ + {% for counts in counts_by_other_subject %} + 
Joined subject:    {{ counts.subject }}
+Joining records:   {{ counts.total }}
+Unique joiner ids: {{ counts.distinct }}
+-> {% if let Some(browseable_uri) = counts.subject|to_browseable -%}
+    browse record
+  {%- endif %}
+ {% endfor %} + + {% if let Some(c) = cursor %} +
+ + + + {% for did in query.did %} + + {% endfor %} + {% for otherSubject in query.other_subject %} + + {% endfor %} + + + +
+ {% else %} + + {% endif %}
Raw JSON response diff --git a/constellation/templates/hello.html.j2 b/constellation/templates/hello.html.j2 index 51de4c9..a085a27 100644 --- a/constellation/templates/hello.html.j2 +++ b/constellation/templates/hello.html.j2 @@ -55,6 +55,32 @@ {% call try_it::get_backlinks("at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e", "app.bsky.feed.like:subject.uri", [""], 16) %} +

GET /xrpc/blue.microcosm.links.getManyToManyCounts

+ +

TODO: description

+ +

Query parameters:

+ +
    +

  • subject: required, must url-encode. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r

    • +

  • source: required. Example: app.bsky.feed.like:subject.uri

    • +

  • pathToOther: required. Path to the secondary link in the many-to-many record. Example: otherThing.uri

    • +

  • did: optional, filter links to those from specific users. Include multiple times to filter by multiple users. Example: did=did:plc:vc7f4oafdgxsihk4cry2xpze&did=did:plc:vc7f4oafdgxsihk4cry2xpze

    • +

  • otherSubject: optional, filter secondary links to specific subjects. Include multiple times to filter by multiple users. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r

    • +

  • limit: optional. Default: 16. Maximum: 100

    • +
+ +

Try it:

+ {% call try_it::get_many_to_many_counts( + "at://did:plc:a4pqq234yw7fqbddawjo7y35/app.bsky.feed.post/3m237ilwc372e", + "app.bsky.feed.like:subject.uri", + "otherThing.uri", + [""], + [""], + 16, + ) %} + +

GET /links

A list of records linking to a target.

diff --git a/constellation/templates/try-it-macros.html.j2 b/constellation/templates/try-it-macros.html.j2 index 1a48503..6e765b6 100644 --- a/constellation/templates/try-it-macros.html.j2 +++ b/constellation/templates/try-it-macros.html.j2 @@ -1,6 +1,6 @@ {% macro get_backlinks(subject, source, dids, limit) %}
- 
GET /links
+    
GET /xrpc/blue.microcosm.links.getBacklinks
   ?subject=    
   &source=     
   {%- for did in dids %}{% if !did.is_empty() %}
@@ -24,6 +24,48 @@
   
 {% endmacro %}
 
+{% macro get_many_to_many_counts(subject, source, pathToOther, dids, otherSubjects, limit) %}
+  
+    
GET /xrpc/blue.microcosm.links.getManyToManyCounts
+  ?subject=      
+  &source=       
+  &pathToOther=  
+  {%- for did in dids %}{% if !did.is_empty() %}
+  &did=          {% endif %}{% endfor %}
+                 
+  {%- for otherSubject in otherSubjects %}{% if !otherSubject.is_empty() %}
+  &otherSubject= {% endif %}{% endfor %}
+                 
+  &limit=         

+  
+  
+{% endmacro %}
+
 {% macro links(target, collection, path, dids, limit) %}
   

     
GET /links
-- 
2.51.2