From a5b2355d0c6a084f2c021d517bf5ee80123d108c Mon Sep 17 00:00:00 2001 From: timonrieger Date: Sun, 3 May 2026 16:27:12 +0200 Subject: [PATCH] document tri-state matrix --- mobile/openapi/lib/api/albums_api.dart | 4 ++-- open-api/immich-openapi-specs.json | 2 +- server/src/controllers/album.controller.ts | 17 ++++++++++++++++- 3 files changed, 19 insertions(+), 4 deletions(-) diff --git a/mobile/openapi/lib/api/albums_api.dart b/mobile/openapi/lib/api/albums_api.dart index 6d41b65518..dd35d8eaac 100644 --- a/mobile/openapi/lib/api/albums_api.dart +++ b/mobile/openapi/lib/api/albums_api.dart @@ -499,7 +499,7 @@ class AlbumsApi { /// List all albums /// - /// Retrieve a list of albums available to the authenticated user. + /// Retrieve a list of albums available to the authenticated user. Results are filtered by the `owned` and `shared` query parameters: | `owned` | `shared` | Result | |---------|----------|--------| | — | — | All accessible albums (owned + shared-with-me) | | `true` | — | Only albums owned by the user | | `false` | — | Only albums shared with the user (not owned) | | `true` | `true` | Owned albums that have been shared out | | `true` | `false` | Owned private albums (not shared) | | — | `true` | Owned albums shared out, plus all albums shared with the user | | — | `false` | Owned private albums only (albums shared with the user are always excluded because the user is a non-owner member) | | `false` | `true` | Albums shared with the user (same as `owned=false`) | | `false` | `false` | Empty (logically impossible combination) | /// /// Note: This method returns the HTTP [Response]. /// @@ -550,7 +550,7 @@ class AlbumsApi { /// List all albums /// - /// Retrieve a list of albums available to the authenticated user. + /// Retrieve a list of albums available to the authenticated user. Results are filtered by the `owned` and `shared` query parameters: | `owned` | `shared` | Result | |---------|----------|--------| | — | — | All accessible albums (owned + shared-with-me) | | `true` | — | Only albums owned by the user | | `false` | — | Only albums shared with the user (not owned) | | `true` | `true` | Owned albums that have been shared out | | `true` | `false` | Owned private albums (not shared) | | — | `true` | Owned albums shared out, plus all albums shared with the user | | — | `false` | Owned private albums only (albums shared with the user are always excluded because the user is a non-owner member) | | `false` | `true` | Albums shared with the user (same as `owned=false`) | | `false` | `false` | Empty (logically impossible combination) | /// /// Parameters: /// diff --git a/open-api/immich-openapi-specs.json b/open-api/immich-openapi-specs.json index 3bd9400eb9..74b49f9a59 100644 --- a/open-api/immich-openapi-specs.json +++ b/open-api/immich-openapi-specs.json @@ -1634,7 +1634,7 @@ }, "/albums": { "get": { - "description": "Retrieve a list of albums available to the authenticated user.", + "description": "Retrieve a list of albums available to the authenticated user.\nResults are filtered by the `owned` and `shared` query parameters:\n\n| `owned` | `shared` | Result |\n|---------|----------|--------|\n| — | — | All accessible albums (owned + shared-with-me) |\n| `true` | — | Only albums owned by the user |\n| `false` | — | Only albums shared with the user (not owned) |\n| `true` | `true` | Owned albums that have been shared out |\n| `true` | `false` | Owned private albums (not shared) |\n| — | `true` | Owned albums shared out, plus all albums shared with the user |\n| — | `false` | Owned private albums only (albums shared with the user are always excluded because the user is a non-owner member) |\n| `false` | `true` | Albums shared with the user (same as `owned=false`) |\n| `false` | `false` | Empty (logically impossible combination) |", "operationId": "getAllAlbums", "parameters": [ { diff --git a/server/src/controllers/album.controller.ts b/server/src/controllers/album.controller.ts index 90a8fa5a25..956b57084f 100644 --- a/server/src/controllers/album.controller.ts +++ b/server/src/controllers/album.controller.ts @@ -29,7 +29,22 @@ export class AlbumController { @Authenticated({ permission: Permission.AlbumRead }) @Endpoint({ summary: 'List all albums', - description: 'Retrieve a list of albums available to the authenticated user.', + description: [ + 'Retrieve a list of albums available to the authenticated user.', + 'Results are filtered by the `owned` and `shared` query parameters:', + '', + '| `owned` | `shared` | Result |', + '|---------|----------|--------|', + '| — | — | All accessible albums (owned + shared-with-me) |', + '| `true` | — | Only albums owned by the user |', + '| `false` | — | Only albums shared with the user (not owned) |', + '| `true` | `true` | Owned albums that have been shared out |', + '| `true` | `false` | Owned private albums (not shared) |', + '| — | `true` | Owned albums shared out, plus all albums shared with the user |', + '| — | `false` | Owned private albums only (albums shared with the user are always excluded because the user is a non-owner member) |', + '| `false` | `true` | Albums shared with the user (same as `owned=false`) |', + '| `false` | `false` | Empty (logically impossible combination) |', + ].join('\n'), history: new HistoryBuilder().added('v1').beta('v1').stable('v2'), }) getAllAlbums(@Auth() auth: AuthDto, @Query() query: GetAlbumsDto): Promise {