diff --git a/docs/_config.yml b/docs/_config.yml index 8135056..073e765 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1 +1,10 @@ -title: Keepit service API +title: KeepIT API +description: Digital archive manager +remote_theme: just-the-docs/just-the-docs + +# Required for just-the-docs nav to work +url: "https://khushbub.github.io" +baseurl: "/KeepIt" + +# Keep all nav sections expanded at all times +nav_expand_all: true diff --git a/docs/articles/Resources.md b/docs/articles/Resources.md new file mode 100644 index 0000000..f449eb6 --- /dev/null +++ b/docs/articles/Resources.md @@ -0,0 +1,39 @@ +--- +# markdownlint-disable +# vale off +# tags used by just-the-docs theme +layout: default +title: Resources +parent: KeepIT API +nav_order: 2 +has_children: true +has_toc: true +# tags used by AI files +description: Lists the reference articles available in the documentation +topic_type: overview +tags: + - introduction +categories: + - tutorial +ai_relevance: high +importance: 8 +prerequisites: [] +related_pages: + - /get-all-collection + - /get-collection-by-id +examples: [] +api_endpoints: [] +version: "v1.0" +last_updated: "2026-03-01" +# vale on +# markdownlint-enable +--- + + + +# Resources + +These resource reference articles are available to help you start using the **Keepit Service API**. + +* [Get all collections](get-all-collection.md) +* [Get collections by ID](get-collection-by-id.md) diff --git a/docs/articles/get-all-collection.md b/docs/articles/get-all-collection.md new file mode 100644 index 0000000..b476e0a --- /dev/null +++ b/docs/articles/get-all-collection.md @@ -0,0 +1,108 @@ +--- +# markdownlint-disable +# vale off +# tags used by just-the-docs theme +layout: default +title: Get all collections +parent: Resources +grand_parent: KeepIT API +nav_order: 1 +# tags used by AI files +description: GET all `collections` resources from the service +topic_type: reference +ai_relevance: high +importance: 7 +api_endpoints: /collections +version: "v1.0" +last_updated: "2026-03-01" +# vale on +# markdownlint-enable +--- + + + +# Get all collections + +Returns all the collections archived with the service. + +## Endpoint + +```shell +{base_url}/collections +``` + +## Parameters + +None + +## Request headers + +None + +## Request body + +None + +## Response body + +```json +[ + { + "id": 1, + "name": "Austin Photographs", + "description": "Historical and contemporary photographs of Austin, Texas.", + "location": "Server A, Folder /austin-photos/", + "itemCount": 18 + } +] +``` + +## Examples + +### `GET` example request + +```bash +curl http://localhost:3000/collections +``` + +#### `GET` example response + +```json +[ + { + "id": 1, + "name": "Austin Photographs", + "description": "Historical and contemporary photographs of Austin, Texas.", + "location": "Server A, Folder /austin-photos/", + "itemCount": 18 + }, + { + "id": 2, + "name": "Austin Photographs", + "description": "Historical maps of Austin and surrounding areas.", + "location": "Server A, Folder /austin-maps/", + "itemCount": 12 + }, + { + "id": 3, + "name": "Texas Newspapers", + "description": "Digitized issues of historical Texas newspapers.", + "location": "Server B, Folder /tx-newspapers/", + "itemCount": 34 + }, + { + "id": 4, + "name": "Texas Oral Histories", + "description": "Audio recordings of interviews with Texas residents.", + "location": "Server C, Folder /tx-oral-histories/", + "itemCount": 22 + } +] +``` + +## Response status + +| HTTP status value | Description | +| ------------- | ----------- | +| 200 | **Success:** Requested data returned successfully | +| ECONNREFUSED | Service is offline. Start, or restart the service and try again. | \ No newline at end of file diff --git a/docs/articles/get-collection-by-id.md b/docs/articles/get-collection-by-id.md new file mode 100644 index 0000000..7ed7be9 --- /dev/null +++ b/docs/articles/get-collection-by-id.md @@ -0,0 +1,87 @@ +--- +# markdownlint-disable +# vale off +# tags used by just-the-docs theme +layout: default +title: Get collections by ID +parent: Resources +grand_parent: KeepIT API +nav_order: 2 +# tags used by AI files +description: GET a `collections` resource by ID from the service +topic_type: reference +ai_relevance: high +importance: 7 +api_endpoints: /collections +version: "v1.0" +last_updated: "2026-03-01" +# vale on +# markdownlint-enable +--- + + + +# Get collections by ID + +Returns a archived collections by ID with the service. + +## Endpoint + +```shell +{base_url}/collections/{id} +``` + +## Parameters + +- id - ID of the collection you want to fetch from the Keepit service. + +## Request headers + +None + +## Request body + +None + +## Response body + +```json +[ + { + "id": 1, + "name": "Austin Photographs", + "description": "Historical and contemporary photographs of Austin, Texas.", + "location": "Server A, Folder /austin-photos/", + "itemCount": 18 + } +] +``` + +## Examples + +### `GET` example request + +```bash +curl http://localhost:3000/collections/4 +``` + +#### `GET` example response + +```json +[ + { + "id": 4, + "name": "Texas Oral Histories", + "description": "Audio recordings of interviews with Texas residents.", + "location": "Server C, Folder /tx-oral-histories/", + "itemCount": 22 + } +] +``` + +## Response status + +| HTTP status value | Description | +| ------------- | ----------- | +| 200 | **Success:** Requested data returned successfully | +| ECONNREFUSED | Service is offline. Start, or restart the service and try again. | \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 83ca950..c26973f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,27 @@ +--- +# markdownlint-disable +# vale off +# tags used by just-the-docs theme +layout: default +title: KeepIT API +nav_order: 1 +has_children: true +has_toc: true +# tags used by AI files +description: documentation landing page +topic_type: overview +ai_relevance: high +importance: 8 +related_pages: + - /Resources +version: "v1.0" +last_updated: "2026-03-01" +# vale on +# markdownlint-enable +--- + + + # KeepIT API ## Archive it. Find it. Keep it. @@ -22,19 +46,20 @@ Use this API to manage your digital archive - organize collections, add items, a ### Collections -- Get all collections — `GET /collections` -- Get a collection by ID — `GET /collections/{id}` -- Create a collection — `POST /collections` +- Get all collections - `GET /collections` +- Get collections by ID - `GET /collections/{id}` +- Create a collection - `POST /collections` ### Items -- Get all items — `GET /items` -- Get an item by ID — `GET /items/{id}` -- Create an item — `POST /items` +- Get all items - `GET /items` +- Get an item by ID - `GET /items/{id}` +- Create an item - `POST /items` ## Learn more -- [Collections resource](#) +* [Get all collections](get-all-collection.md) +* [Get collections by ID](get-collection-by-id.md) ## References