From 5b7999b6eaf32e7c4044e29ae5f1f627c6652c34 Mon Sep 17 00:00:00 2001
From: rzmk <30333942+rzmk@users.noreply.github.com>
Date: Fri, 24 Oct 2025 01:10:08 -0400
Subject: [PATCH] feat(docs): add more endpoints
---
docs/content/docs/format_autocomplete.mdx | 20 ++
docs/content/docs/group_autocomplete.mdx | 20 ++
.../docs/organization_autocomplete.mdx | 20 ++
docs/content/docs/package_autocomplete.mdx | 26 ++
docs/content/docs/resource_search.mdx | 127 ++++++++
docs/content/docs/user_autocomplete.mdx | 20 ++
docs/lib/openapi.yml | 285 ++++++++++++++----
7 files changed, 454 insertions(+), 64 deletions(-)
create mode 100644 docs/content/docs/format_autocomplete.mdx
create mode 100644 docs/content/docs/group_autocomplete.mdx
create mode 100644 docs/content/docs/organization_autocomplete.mdx
create mode 100644 docs/content/docs/package_autocomplete.mdx
create mode 100644 docs/content/docs/resource_search.mdx
create mode 100644 docs/content/docs/user_autocomplete.mdx
diff --git a/docs/content/docs/format_autocomplete.mdx b/docs/content/docs/format_autocomplete.mdx
new file mode 100644
index 0000000..5d0d862
--- /dev/null
+++ b/docs/content/docs/format_autocomplete.mdx
@@ -0,0 +1,20 @@
+---
+title: format_autocomplete
+full: true
+_openapi:
+ method: POST
+ route: format_autocomplete
+ toc: []
+ structuredData:
+ headings: []
+ contents:
+ - content: |
+ Return a list of resource formats whose names contain a string.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Return a list of resource formats whose names contain a string.
+
+
+
\ No newline at end of file
diff --git a/docs/content/docs/group_autocomplete.mdx b/docs/content/docs/group_autocomplete.mdx
new file mode 100644
index 0000000..ebe3d1f
--- /dev/null
+++ b/docs/content/docs/group_autocomplete.mdx
@@ -0,0 +1,20 @@
+---
+title: group_autocomplete
+full: true
+_openapi:
+ method: POST
+ route: group_autocomplete
+ toc: []
+ structuredData:
+ headings: []
+ contents:
+ - content: |
+ Return a list of group names that contain a string.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Return a list of group names that contain a string.
+
+
+
\ No newline at end of file
diff --git a/docs/content/docs/organization_autocomplete.mdx b/docs/content/docs/organization_autocomplete.mdx
new file mode 100644
index 0000000..6c62ca4
--- /dev/null
+++ b/docs/content/docs/organization_autocomplete.mdx
@@ -0,0 +1,20 @@
+---
+title: organization_autocomplete
+full: true
+_openapi:
+ method: POST
+ route: organization_autocomplete
+ toc: []
+ structuredData:
+ headings: []
+ contents:
+ - content: |
+ Return a list of organization names that contain a string.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Return a list of organization names that contain a string.
+
+
+
\ No newline at end of file
diff --git a/docs/content/docs/package_autocomplete.mdx b/docs/content/docs/package_autocomplete.mdx
new file mode 100644
index 0000000..cdf3f2d
--- /dev/null
+++ b/docs/content/docs/package_autocomplete.mdx
@@ -0,0 +1,26 @@
+---
+title: package_autocomplete
+full: true
+_openapi:
+ method: POST
+ route: package_autocomplete
+ toc: []
+ structuredData:
+ headings: []
+ contents:
+ - content: >
+ Return a list of datasets (packages) that match a string.
+
+
+ Datasets with names or titles that contain the query string will be
+ returned.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Return a list of datasets (packages) that match a string.
+
+Datasets with names or titles that contain the query string will be returned.
+
+
+
\ No newline at end of file
diff --git a/docs/content/docs/resource_search.mdx b/docs/content/docs/resource_search.mdx
new file mode 100644
index 0000000..401279e
--- /dev/null
+++ b/docs/content/docs/resource_search.mdx
@@ -0,0 +1,127 @@
+---
+title: resource_search
+full: true
+_openapi:
+ method: POST
+ route: resource_search
+ toc: []
+ structuredData:
+ headings: []
+ contents:
+ - content: >
+ Searches for resources in public Datasets satisfying the search
+ criteria.
+
+
+ It returns a dictionary with 2 fields: `count` and `results`. The
+ `count` field contains the total number of Resources found without the
+ limit or query parameters having an effect. The `results` field is a
+ list of dictized Resource objects.
+
+
+ The 'query' parameter is a required field. It is a string of the form
+ `{field}:{term}` or a list of strings, each of the same form. Within
+ each string, `{field}` is a field or extra field on the Resource
+ domain object.
+
+
+ If `{field}` is `"hash"`, then an attempt is made to match the
+ `{term}` as a *prefix* of the `Resource.hash` field.
+
+
+ If `{field}` is an extra field, then an attempt is made to match
+ against the extra fields stored against the Resource.
+
+
+ Note: The search is limited to search against extra fields declared in
+ the config setting `ckan.extra_resource_fields`.
+
+
+ Note: Due to a Resource's extra fields being stored as a json blob,
+ the match is made against the json string representation. As such,
+ false positives may occur:
+
+
+ If the search criteria is:
+
+
+ ```
+
+ query = "field1:term1"
+
+ ```
+
+
+ Then a json blob with the string representation of:
+
+
+ ```json
+
+ {"field1": "foo", "field2": "term1"}
+
+ ```
+
+
+ will match the search criteria! This is a known short-coming of this
+ approach.
+
+
+ All matches are made ignoring case; and apart from the `"hash"` field,
+ a term matches if it is a substring of the field’s value.
+
+
+ Finally, when specifying more than one search criteria, the criteria
+ are AND-ed together.
+
+
+ The `order` parameter is used to control the ordering of the results.
+ Currently only ordering one field is available, and in ascending order
+ only.
+
+
+ The context may contain a flag, *search_query*, which if True will
+ make this action behave as if being used by the internal search api.
+ ie - the results will not be dictized, and SearchErrors are thrown for
+ bad search queries (rather than ValidationErrors).
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Searches for resources in public Datasets satisfying the search criteria.
+
+It returns a dictionary with 2 fields: `count` and `results`. The `count` field contains the total number of Resources found without the limit or query parameters having an effect. The `results` field is a list of dictized Resource objects.
+
+The 'query' parameter is a required field. It is a string of the form `{field}:{term}` or a list of strings, each of the same form. Within each string, `{field}` is a field or extra field on the Resource domain object.
+
+If `{field}` is `"hash"`, then an attempt is made to match the `{term}` as a *prefix* of the `Resource.hash` field.
+
+If `{field}` is an extra field, then an attempt is made to match against the extra fields stored against the Resource.
+
+Note: The search is limited to search against extra fields declared in the config setting `ckan.extra_resource_fields`.
+
+Note: Due to a Resource's extra fields being stored as a json blob, the match is made against the json string representation. As such, false positives may occur:
+
+If the search criteria is:
+
+```
+query = "field1:term1"
+```
+
+Then a json blob with the string representation of:
+
+```json
+{"field1": "foo", "field2": "term1"}
+```
+
+will match the search criteria! This is a known short-coming of this approach.
+
+All matches are made ignoring case; and apart from the `"hash"` field, a term matches if it is a substring of the field’s value.
+
+Finally, when specifying more than one search criteria, the criteria are AND-ed together.
+
+The `order` parameter is used to control the ordering of the results. Currently only ordering one field is available, and in ascending order only.
+
+The context may contain a flag, *search_query*, which if True will make this action behave as if being used by the internal search api. ie - the results will not be dictized, and SearchErrors are thrown for bad search queries (rather than ValidationErrors).
+
+
+
\ No newline at end of file
diff --git a/docs/content/docs/user_autocomplete.mdx b/docs/content/docs/user_autocomplete.mdx
new file mode 100644
index 0000000..c0d4243
--- /dev/null
+++ b/docs/content/docs/user_autocomplete.mdx
@@ -0,0 +1,20 @@
+---
+title: user_autocomplete
+full: true
+_openapi:
+ method: POST
+ route: user_autocomplete
+ toc: []
+ structuredData:
+ headings: []
+ contents:
+ - content: |
+ Return a list of user names that contain a string.
+---
+
+{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
+
+Return a list of user names that contain a string.
+
+
+
\ No newline at end of file
diff --git a/docs/lib/openapi.yml b/docs/lib/openapi.yml
index d21a867..9914ffd 100644
--- a/docs/lib/openapi.yml
+++ b/docs/lib/openapi.yml
@@ -585,81 +585,105 @@ paths:
include_plugin_extras:
type: boolean
description: "include the internal plugin extras object (sysadmin only, default: `False`)"
- status_show:
- get:
- operationId: status_show
- summary: status_show
- description: This endpoint shows information about the CKAN instance.
- x-codeSamples:
- - lang: rust
- label: Rust SDK (ckanaction) example
- source: |
- use dotenvy::dotenv;
-
- #[tokio::main]
- async fn main() -> Result<(), Box> {
- // Load environment variables from .env file
- dotenv()?;
-
- // Initialize and build CKAN struct
- let ckan = ckanaction::CKAN::builder()
- .url("http://localhost:5000")
- .token(dotenvy::var("CKAN_API_TOKEN")?)
- .build();
-
- // Send request to /status_show and print output
- let result = ckan.status_show().await?;
- println!("{result:#?}");
-
- Ok(())
- }
- 'package_list':
+ package_autocomplete:
post:
- operationId: package_list
- summary: package_list
- description: This endpoint lists CKAN resources.
+ operationId: package_autocomplete
+ summary: package_autocomplete
+ description: |
+ Return a list of datasets (packages) that match a string.
+
+ Datasets with names or titles that contain the query string will be returned.
requestBody:
required: false
content:
application/json:
schema:
- # required:
- # - project_uuid
type: object
properties:
+ q:
+ type: string
+ description: the string to search for
limit:
type: integer
- description: if given, the list of datasets will be broken into pages of at most `limit` datasets per page and only one page will be returned at a time
- offset:
+ # Original docs typo? Should this be max number of datasets?
+ description: "the maximum number of datasets to return (default: `10`)"
+ format_autocomplete:
+ post:
+ operationId: format_autocomplete
+ summary: format_autocomplete
+ description: |
+ Return a list of resource formats whose names contain a string.
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ q:
+ type: string
+ description: the string to search for
+ limit:
type: integer
- description: when limit is given, the offset to start returning packages from
- x-codeSamples:
- - lang: rust
- label: Rust SDK (ckanaction) example
- source: |
- use dotenvy::dotenv;
-
- #[tokio::main]
- async fn main() -> Result<(), Box> {
- // Load environment variables from .env file
- dotenv()?;
-
- // Initialize and build CKAN struct
- let ckan = ckanaction::CKAN::builder()
- .url("http://localhost:5000")
- .token(dotenvy::var("CKAN_API_TOKEN")?)
- .build();
-
- // Send request to /package_list and print output
- let result = ckan.package_list()
- .limit(5) // <-- This is an optional parameter you can remove
- .call()
- .await?;
- println!("{result:#?}");
-
- Ok(())
- }
- 'package_search':
+ description: "the maximum number of resource formats to return (default: `5`)"
+ user_autocomplete:
+ post:
+ operationId: user_autocomplete
+ summary: user_autocomplete
+ description: |
+ Return a list of user names that contain a string.
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ q:
+ type: string
+ description: the string to search for
+ limit:
+ type: integer
+ description: "the maximum number of user names to return (default: `20`)"
+ group_autocomplete:
+ post:
+ operationId: group_autocomplete
+ summary: group_autocomplete
+ description: |
+ Return a list of group names that contain a string.
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ q:
+ type: string
+ description: the string to search for
+ limit:
+ type: integer
+ description: "the maximum number of groups to return (default: `20`)"
+ organization_autocomplete:
+ post:
+ operationId: organization_autocomplete
+ summary: organization_autocomplete
+ description: |
+ Return a list of organization names that contain a string.
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ q:
+ type: string
+ description: the string to search for
+ limit:
+ type: integer
+ description: "the maximum number of organizations to return (default: `20`)"
+ package_search:
post:
operationId: package_search
summary: package_search
@@ -766,5 +790,138 @@ paths:
.await?;
println!("{result:#?}");
+ Ok(())
+ }
+ resource_search:
+ post:
+ operationId: resource_search
+ summary: resource_search
+ description: |
+ Searches for resources in public Datasets satisfying the search criteria.
+
+ It returns a dictionary with 2 fields: `count` and `results`. The `count` field contains the total number of Resources found without the limit or query parameters having an effect. The `results` field is a list of dictized Resource objects.
+
+ The 'query' parameter is a required field. It is a string of the form `{field}:{term}` or a list of strings, each of the same form. Within each string, `{field}` is a field or extra field on the Resource domain object.
+
+ If `{field}` is `"hash"`, then an attempt is made to match the `{term}` as a *prefix* of the `Resource.hash` field.
+
+ If `{field}` is an extra field, then an attempt is made to match against the extra fields stored against the Resource.
+
+ Note: The search is limited to search against extra fields declared in the config setting `ckan.extra_resource_fields`.
+
+ Note: Due to a Resource's extra fields being stored as a json blob, the match is made against the json string representation. As such, false positives may occur:
+
+ If the search criteria is:
+
+ ```
+ query = "field1:term1"
+ ```
+
+ Then a json blob with the string representation of:
+
+ ```json
+ {"field1": "foo", "field2": "term1"}
+ ```
+
+ will match the search criteria! This is a known short-coming of this approach.
+
+ All matches are made ignoring case; and apart from the `"hash"` field, a term matches if it is a substring of the field’s value.
+
+ Finally, when specifying more than one search criteria, the criteria are AND-ed together.
+
+ The `order` parameter is used to control the ordering of the results. Currently only ordering one field is available, and in ascending order only.
+
+ The context may contain a flag, *search_query*, which if True will make this action behave as if being used by the internal search api. ie - the results will not be dictized, and SearchErrors are thrown for bad search queries (rather than ValidationErrors).
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ query:
+ type: string
+ description: the search criteria
+ order_by:
+ type: string
+ description: a field on the Resource model that orders the results
+ offset:
+ type: integer
+ description: apply an offset to the query
+ limit:
+ type: integer
+ description: apply a limit to the query
+ status_show:
+ get:
+ operationId: status_show
+ summary: status_show
+ description: This endpoint shows information about the CKAN instance.
+ x-codeSamples:
+ - lang: rust
+ label: Rust SDK (ckanaction) example
+ source: |
+ use dotenvy::dotenv;
+
+ #[tokio::main]
+ async fn main() -> Result<(), Box> {
+ // Load environment variables from .env file
+ dotenv()?;
+
+ // Initialize and build CKAN struct
+ let ckan = ckanaction::CKAN::builder()
+ .url("http://localhost:5000")
+ .token(dotenvy::var("CKAN_API_TOKEN")?)
+ .build();
+
+ // Send request to /status_show and print output
+ let result = ckan.status_show().await?;
+ println!("{result:#?}");
+
+ Ok(())
+ }
+ 'package_list':
+ post:
+ operationId: package_list
+ summary: package_list
+ description: This endpoint lists CKAN resources.
+ requestBody:
+ required: false
+ content:
+ application/json:
+ schema:
+ # required:
+ # - project_uuid
+ type: object
+ properties:
+ limit:
+ type: integer
+ description: if given, the list of datasets will be broken into pages of at most `limit` datasets per page and only one page will be returned at a time
+ offset:
+ type: integer
+ description: when limit is given, the offset to start returning packages from
+ x-codeSamples:
+ - lang: rust
+ label: Rust SDK (ckanaction) example
+ source: |
+ use dotenvy::dotenv;
+
+ #[tokio::main]
+ async fn main() -> Result<(), Box> {
+ // Load environment variables from .env file
+ dotenv()?;
+
+ // Initialize and build CKAN struct
+ let ckan = ckanaction::CKAN::builder()
+ .url("http://localhost:5000")
+ .token(dotenvy::var("CKAN_API_TOKEN")?)
+ .build();
+
+ // Send request to /package_list and print output
+ let result = ckan.package_list()
+ .limit(5) // <-- This is an optional parameter you can remove
+ .call()
+ .await?;
+ println!("{result:#?}");
+
Ok(())
}
\ No newline at end of file