Swagger API Help

[Luke 37063]

@softworkz will take a look at it. Thanks.

[softworkz 3335]

Hi guys,

what Emby does here is really simple:

When you query for the OpenApi document, Emby replaces the server information in the document with the request URL it sees. That means, whatever is in the document is matching the URL of the request being made to Emby. When you have something in-between, Emby cannot know this. It can only put that information into the document that it "sees".

Originally, I had though about adding the "known" official Emby addresses to the server list as well, but I concluded that this would be a security issue. The openapi document is freely accessible (without authentication) and when we would add those official addresses (like you see on the dashboard), this might reveal information that should not be revealed.

For that reason, we only return a server address based on the request URL in the openapi spec document.

 

[softworkz 3335]

You can verify this by activating debug logging in Emby server, making a request for the openapi document and then looking at the log (search for /emby/openapi) to see to which  url the request has been made.

[ShadowKindjal 19]

3 minutes ago, softworkz said:

You can verify this by activating debug logging in Emby server, making a request for the openapi document and then looking at the log (search for /emby/openapi) to see to which  url the request has been made.

This is the snippet from my log for the swagger api request.

 

2022-09-02 19:21:18.126 Debug Server: http/1.1 GET http://emby_remote_ip/emby/openapi. UserAgent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36
2022-09-02 19:21:18.198 Debug Server: http/1.1 Response 200 to host48. Time: 72ms. http://emby_remote_ip/emby/openapi
2022-09-02 19:21:18.399 Debug Server: http/1.1 GET http://emby_remote_ip/emby/openapi. UserAgent: swagger-validator
2022-09-02 19:21:18.477 Debug Server: http/1.1 Response 200 to host62. Time: 78ms. http://emby_remote_ip/emby/openapi

 

[ShadowKindjal 19]

If it helps, this is setup for my reverse proxy from nginx.

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    proxy_buffering off;

    server_name emby.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
        include /config/nginx/proxy.conf;
        resolver 127.0.0.11 valid=30s;
        set $upstream_app emby;
        set $upstream_port 8096;
        set $upstream_proto http;
        set $upstream_ip 192.168.1.100;
        proxy_pass $upstream_proto://$upstream_ip:$upstream_port;

        proxy_hide_header X-Powered-By;
        proxy_set_header Range $http_range;
        proxy_set_header If-Range $http_if_range;
        proxy_set_header X-Real-IP $http_CF_Connecting_IP;
#        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        add_header 'Referrer-Policy' 'origin-when-cross-origin';
        add_header Strict-Transport-Security "max-age=15552000; preload" always;
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-XSS-Protection "1; mode=block" always;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $http_connection;
   }
}

 

[ShadowKindjal 19]

13 minutes ago, softworkz said:

Hi guys,

what Emby does here is really simple:

When you query for the OpenApi document, Emby replaces the server information in the document with the request URL it sees. That means, whatever is in the document is matching the URL of the request being made to Emby. When you have something in-between, Emby cannot know this. It can only put that information into the document that it "sees".

Originally, I had though about adding the "known" official Emby addresses to the server list as well, but I concluded that this would be a security issue. The openapi document is freely accessible (without authentication) and when we would add those official addresses (like you see on the dashboard), this might reveal information that should not be revealed.

For that reason, we only return a server address based on the request URL in the openapi spec document.

 

I do have a question after reviewing the logs. I understand that Emby can only use information that it sees but within my log I see that Emby is passing the remote IP over the HTTP protocol to Swagger. Is there an opportunity to pass the in-home/LAN IP address to Swagger as well and give the user and option to use either. I wonder if this would reduce the security risk you are referring to. This way I could at least use Swagger to test the API within the local network of the server.

[softworkz 3335]

51 minutes ago, ShadowKindjal said:

I do have a question after reviewing the logs. I understand that Emby can only use information that it sees but within my log I see that Emby is passing the remote IP over the HTTP protocol to Swagger. Is there an opportunity to pass the in-home/LAN IP address to Swagger as well and give the user and option to use either. I wonder if this would reduce the security risk you are referring to. This way I could at least use Swagger to test the API within the local network of the server.

When you access the server dashboard locally (via http://localhost:8096/), then it should work.

[softworkz 3335]

The https://swagger.emby.media/ URL is always https because otherwise you would get CORS errors.

It's essentially the open-source code from swagger.io with a few adaptions, but we haven't touched it for quite a while.
The reasons to host our own version were

• to set you guys free from all the advertisements and distractions on the original sites
• to provide a one-click-working experience: you are immediately logged in with an api token and can try out stuff

I never understood why the swagger site code doesn't support entering a custom api url and restricts to the ones in the document, that doesn't make much sense, but well - this is just a playground to explore the Emby REST API. This limitation doesn't restrict you from using the API in any other way.

BTW: There's a whole bunch of stuff for developers coming up shortly, stay tuned!

[ShadowKindjal 19]

1 hour ago, softworkz said:

When you access the server dashboard locally (via http://localhost:8096/), then it should work.

I didn't access it via the localhost but instead another computer on the LAN and I got this error message.

[softworkz 3335]

In that case, you need a browser extension to disable CORS. There are several available for all browsers.

IIRC, it doesn't work when changing the swagger.emby.media to http

[Luke 37063]

@ShadowKindjal @pir8radio Has this helped you resolve this?

[pir8radio 1292]

4 hours ago, Luke said:

@ShadowKindjal @pir8radio Has this helped you resolve this?

accidently tag me?

[Luke 37063]

1 minute ago, pir8radio said:

accidently tag me?

No, in page one you had confirmed a problem when trying to use swagger over a remote connection and a reverse proxy redirect.

Anyway I've got some changes in the server coming that will allow this to work.

[ShadowKindjal 19]

On 10/13/2022 at 5:06 PM, Luke said:

@ShadowKindjal @pir8radio Has this helped you resolve this?

No, the original issue I brought up did not get resolved. I'm only able to access swagger from the computer emby is installed on. Trying to access swagger via the LAN fails because of CORS and trying to access swagger thru reverse proxy defaults to the HTTP protocol. Nothing has changed.

[softworkz 3335]

5 minutes ago, ShadowKindjal said:

No, the original issue I brought up did not get resolved. I'm only able to access swagger from the computer emby is installed on. Trying to access swagger via the LAN fails because of CORS and trying to access swagger thru reverse proxy defaults to the HTTP protocol. Nothing has changed.

The change he made is not in the current beta.

But you know that this is only affecting the Swagger interactive tryout to be used for testing API requests during development?
This does not affect the ability of an application you are developing to access Emby server (even with your kind of setup).

[ShadowKindjal 19]

6 minutes ago, softworkz said:

The change he made is not in the current beta.

But you know that this is only affecting the Swagger interactive tryout to be used for testing API requests during development?
This does not affect the ability of an application you are developing to access Emby server (even with your kind of setup).

Yes, I'm aware of the limited scope of this. I have multiple applications that i have written to work without issue that utilizes the API. It's purely a matter of convenience. I'm currently remoting into the server to run swagger and it's just an annoying extra step to test the API.

[softworkz 3335]

Ah alright understood.

We have some cool news for developers using the API coming up. What's our language (programming)?

[Happy2Play 8281]

Have you tried looking at browser flag options?

In Chrome/Edge entered IP or Hostname depending how you connect.  edge://flags / chrome://flags

 

 

[rbjtech 4260]

10 hours ago, Happy2Play said:

Have you tried looking at browser flag options?

In Chrome/Edge entered IP or Hostname depending how you connect.  edge://flags / chrome://flags

 

 

This is great - thanks H2P - this allows me to use Swagger without needing to RDP to the host and use localhost !

Edited October 17, 2022 by rbjtech

[ShadowKindjal 19]

Was there an update to the swagger implementation? I'm now able to process API calls from within the Swagger page without issue even though the server is still identified as HTTP instead of HTTPS. Running the code outside of swagger requires that I use the HTTPS variant of the web address but everything is now working flawlessly within the Swagger website!

[Luke 37063]

Yes a fix was made. Thanks.

[ShadowKindjal 19]

On 10/15/2022 at 11:34 PM, softworkz said:

Ah alright understood.

We have some cool news for developers using the API coming up. What's our language (programming)?

Sorry, just noticed your question. I'm using javascript right now to integrate with my website.

[ShadowKindjal 19]

On 11/17/2022 at 12:44 PM, Luke said:

Yes a fix was made. Thanks.

Was there another change? Attempting to use any Swagger functions results in the following server response. "TypeError: Failed to fetch"

Functionality returns if I copy the request URL and replace HTTP with HTTPS

Edited March 28, 2023 by ShadowKindjal

[Luke 37063]

43 minutes ago, ShadowKindjal said:

Was there another change? Attempting to use any Swagger functions results in the following server response. "TypeError: Failed to fetch"

Functionality returns if I copy the request URL and replace HTTP with HTTPS

Browser requirements are generally going to restrict it to https only.

[ShadowKindjal 19]

On 11/17/2022 at 12:33 PM, ShadowKindjal said:

Was there an update to the swagger implementation? I'm now able to process API calls from within the Swagger page without issue even though the server is still identified as HTTP instead of HTTPS. Running the code outside of swagger requires that I use the HTTPS variant of the web address but everything is now working flawlessly within the Swagger website!

I'm confused then. Everything was definitely working from within swagger but with a http request address