immich-app/immich
1
0
Fork 0
mirror of https://github.com/immich-app/immich.git synced 2026-02-05 00:30:57 +03:00
Code Issues 11 Packages Projects Releases 10 Wiki Activity

[BUG] OpenAPI Immich Server Spec - Client generation is not usable #834

New Issue
Closed
opened 2026-02-04 22:53:28 +03:00 by OVERLORD · 3 comments
OVERLORD commented 2026-02-04 22:53:28 +03:00
Owner
Copy Link

Originally created by @ckocyigit on GitHub (Apr 26, 2023).

The bug

I have generated a python client from the immich server openapi spec and noticed some flaws which I will list here:

  • Content Types for AuthenticationApi.Login.login cannot handle response from server with 'charset=utf-8'
  • Configuration is not generating 'access_token' attribute correctly
  • e.g. Asset.downloadFile content type for generated client is expected to be "application/octet-stream" but "image/jpeg" is incoming
  • TBD..

The OS that Immich Server is running on

Unraid 6.12.0-rc2

Version of Immich Server

1.54.1

Version of Immich Mobile App

1.54.0 build.77

Platform with the issue

  • Server
  • Web
  • Mobile

Your docker-compose.yml content

skip

Your .env content

skip

Reproduction steps

1. Generate a client I would assume of any kind or for python
2. Try utilizing the client
3. Fail :()

Additional information

No response

Originally created by @ckocyigit on GitHub (Apr 26, 2023). ### The bug I have generated a python client from the immich server openapi spec and noticed some flaws which I will list here: - Content Types for AuthenticationApi.Login.login cannot handle response from server with 'charset=utf-8' - Configuration is not generating 'access_token' attribute correctly - e.g. Asset.downloadFile content type for generated client is expected to be "application/octet-stream" but "image/jpeg" is incoming - TBD.. ### The OS that Immich Server is running on Unraid 6.12.0-rc2 ### Version of Immich Server 1.54.1 ### Version of Immich Mobile App 1.54.0 build.77 ### Platform with the issue - [X] Server - [ ] Web - [ ] Mobile ### Your docker-compose.yml content ```YAML skip ``` ### Your .env content ```Shell skip ``` ### Reproduction steps ```bash 1. Generate a client I would assume of any kind or for python 2. Try utilizing the client 3. Fail :() ``` ### Additional information _No response_
OVERLORD commented 2026-02-04 22:53:37 +03:00
Author
Owner
Copy Link

@michelheusschen commented on GitHub (May 1, 2023):

  • Content Types for AuthenticationApi.Login.login cannot handle response from server with 'charset=utf-8'

Are you saying the OpenAPI docs have the media type listed as application/json, but you're seeing a Content-Type header with the value application/json; charset=utf-8 in the response? Having the charset explicitly defined shouldn't lead to issues with UTF-8 also being the default for JSON responses.

  • Configuration is not generating 'access_token' attribute correctly

I'm guessing you're trying to use the Python snippet generated by the API docs on the website, right? It doesn't seem to include the cookie header, but it is defined in our OpenAPI spec. It looks like a limitation in the package that is being used for generating these docs, if you select bearer auth the correct header is added.

  • e.g. Asset.downloadFile content type for generated client is expected to be "application/octet-stream" but "image/jpeg" is incoming

application/octet-stream is the default content type for indicating a binary file and is often used for unknown file types. It could be further specified with something like image/* and video/* but I don't think it's a huge issue.

Below an example in Python that showcases a few different ways for authentication:

import requests

url = "http://localhost:2283/api/album"

payload={}
headers = {
	'Accept': 'application/json',

	# Choose one of these headers
	'Authorization': 'Bearer *access token*',
	'Cookie': 'immich_access_token=*access token*',
	'x-api-key': '*api key*'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
@michelheusschen commented on GitHub (May 1, 2023): > * Content Types for AuthenticationApi.Login.login cannot handle response from server with 'charset=utf-8' Are you saying the OpenAPI docs have the media type listed as `application/json`, but you're seeing a `Content-Type` header with the value `application/json; charset=utf-8` in the response? Having the charset explicitly defined shouldn't lead to issues with UTF-8 also being the default for JSON responses. > * Configuration is not generating 'access_token' attribute correctly I'm guessing you're trying to use the Python snippet generated by the API docs on the [website](https://immich.app/docs/api), right? It doesn't seem to include the cookie header, but it is defined in our [OpenAPI spec](https://github.com/immich-app/immich/blob/main/server/immich-openapi-specs.json#L3459-L3463). It looks like a limitation in the package that is being used for generating these docs, if you select bearer auth the correct header is added. > * e.g. Asset.downloadFile content type for generated client is expected to be "application/octet-stream" but "image/jpeg" is incoming `application/octet-stream` is the default content type for indicating a binary file and is often used for unknown file types. It could be further specified with something like `image/*` and `video/*` but I don't think it's a huge issue. Below an example in Python that showcases a few different ways for authentication: ```python import requests url = "http://localhost:2283/api/album" payload={} headers = { 'Accept': 'application/json', # Choose one of these headers 'Authorization': 'Bearer *access token*', 'Cookie': 'immich_access_token=*access token*', 'x-api-key': '*api key*' } response = requests.request("GET", url, headers=headers, data=payload) print(response.text) ```
OVERLORD commented 2026-02-04 22:53:45 +03:00
Author
Owner
Copy Link

@alextran1502 commented on GitHub (May 6, 2023):

Add api key in #2362 to potentially fix this issue

@alextran1502 commented on GitHub (May 6, 2023): Add api key in #2362 to potentially fix this issue
OVERLORD commented 2026-02-04 22:53:51 +03:00
Author
Owner
Copy Link

@ckocyigit commented on GitHub (May 10, 2023):

Sorry for the late response @michelheusschen

I understand that this topic might be difficult to understand with the information I have given.
That's why I will try to add specific examples for each bulletpoint below:

Also a small description how I generated a python client.

I utilized server/immich-openapi-specs.json and openapi-generator like this to be exact:

openapi-generator-cli generate -i https://raw.githubusercontent.com/immich-app/immich/main/server/immich-openapi-specs.json -g python --package-name immich --global-property apiTests=false,modelTests=false,modelDocs=false,apiDocs=false

Configuration is not generating 'access_token' attribute correctly

The generator builds some generic code for basic handling. One of them is the "configuration.py". If you inspect it after generation you will notice a 'access_token' attribute missing in the constructor definition. I had to manually add e.g. self.access_token = access_token. This is probably caused by missing information in the spec file.

Content Types for AuthenticationApi.Login.login cannot handle response from server with 'charset=utf-8'

Yes, you are correct and I would also assume the same as you did with:

Having the charset explicitly defined shouldn't lead to issues

But it still fails as the generated client code explicitly expects this exact string: "application/json"

image

actually this also explains:

e.g. Asset.downloadFile content type for generated client is expected to be "application/octet-stream" but "image/jpeg" is incoming

@ckocyigit commented on GitHub (May 10, 2023): Sorry for the late response @michelheusschen I understand that this topic might be difficult to understand with the information I have given. That's why I will try to add specific examples for each bulletpoint below: Also a small description how I generated a python client. I utilized `server/immich-openapi-specs.json` and openapi-generator like this to be exact: `openapi-generator-cli generate -i https://raw.githubusercontent.com/immich-app/immich/main/server/immich-openapi-specs.json -g python --package-name immich --global-property apiTests=false,modelTests=false,modelDocs=false,apiDocs=false` > Configuration is not generating 'access_token' attribute correctly The generator builds some generic code for basic handling. One of them is the "configuration.py". If you inspect it after generation you will notice a 'access_token' attribute missing in the constructor definition. I had to manually add e.g. `self.access_token = access_token`. This is probably caused by missing information in the spec file. > Content Types for AuthenticationApi.Login.login cannot handle response from server with 'charset=utf-8' Yes, you are correct and I would also assume the same as you did with: > Having the charset explicitly defined shouldn't lead to issues But it still fails as the generated client code explicitly expects this exact string: "application/json" ![image](https://github.com/immich-app/immich/assets/60385015/08b70c71-6916-4a8d-abda-3dd8fd1597a3) actually this also explains: `e.g. Asset.downloadFile content type for generated client is expected to be "application/octet-stream" but "image/jpeg" is incoming`
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
accessibility
changelog:enhancement
changelog:security
changelog:translation
cli
date-time
documentation
external-library
format
good first issue
needs-answer
nice to have
sharing
tech-debt
📱mobile
🖥️web
🗄️server
🧠machine-learning
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
OVERLORD
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: immich-app/immich#834
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?