WiiM HTTP API Docs

You can find all of the documentation and API references at: https://cvdlinden.github.io/wiim-httpapi/
Status: Work in progress!

Exploring the HTTP API for WiiM products by documenting the known endpoints.

The HTTP API can be found on your WiiM device like so:
https://{ip-address}/httpapi.asp?command={command}

First I'll gather all endpoints, then test and elaborate the documentation.

Swagger/OpenAPI

Idea: Use Swagger UI to document the Linkplay HTTP API, that is used by WiiM. Swagger/OpenAPI has a nice documentation format, with a 'try it out' option so you can test to see what the responses are.

Note: The WiiM device has a self-signed certificate, which is deemed unsafe by any modern browser. Therefore this solution uses a reverse proxy that ignores the certificate.

How to use

1. Clone this repo

   git clone https://github.com/cvdlinden/wiim-httpapi.git

   or download the ZIP file and unpack to a folder

2. Do an npm install to install the required packages

3. Copy the config-sample.yaml file to config.yaml

4. Edit config.yaml in your favorite text editor and replace the IP-address(es) with the actual ip address(es) of your WiiM device(s).

   You can find your IP-address in the WiiM Home app > Devices > Settings > Network Status

5. Run node .\index.js

6. You will find the interactive documentation at http://localhost:3000/

Requirements:

• Git: in order to clone this repo. Although you can just download the ZIP file as well.
• Nodejs: in order to run this documentation.

"I don't want to install anything!"

Sure! We've got you!
The entire API documentation is also available on GitHub Pages: WiiM HTTP API Documentation

Note that you won't have the interactive part to talk to your WiiM device and see what the response actually is.

"I found another command that isn't in the list!"

Great!
Linkplay/WiiM haven't documented all commands. And with each new product new commands seem to pop up.
Please be patient, this is still a work in progress. Feel free to test it out yourself first of all.

Add the command you've found to your copy of openapi.yaml, restart node.js and test it out.
If you need help on how to change the openapi.yaml file please see: What Is OpenAPI?

If you want to share your new discovery and add to this documentation and are not afraid to flex some programming skills, you can:

• Fork this repo: Create a new fork
• Make the desired changes to your repo
• If you're happy with the results create a Pull request
• Please state in the PR what the command does AND where you found it
• I will then evaluate, in my own time, and add the changes to the main repo if they make sense

Having none of that? You can also create an new Issue.
Please tell us what the command does AND where you found it.

Development (sources)

Linkplay/WiiM/Arylic HTTP API sources

In no particular order:

• https://www.wiimhome.com/pdf/HTTP%20API%20for%20WiiM%20Products.pdf
• https://github.com/DanBrezeanu/wiim-extended-http-api
• https://github.com/n4archive/LinkPlayAPI/blob/master/api.md
• https://developer.arylic.com/httpapi/#http-api
• https://forum.arylic.com/t/api-files-for-developers/1379
• https://github.com/shumatech/wiimplay/blob/main/wiimdev/wiim.go
• https://github.com/AndersFluur/LinkPlayApi/blob/master/api.md
• https://github.com/Velleman/python-linkplay
• https://github.com/mjcumming/pywiim

https://forum.wiimhome.com/threads/api-for-wiim-amp.3306/

OpenAPI/Swagger sources

What Is OpenAPI?

Swagger Editor, an online editor for OpenAPI:

• https://editor-next.swagger.io/

File > Import File > edit to your liking
Then Save as YAML and JSON
Or Generate Server/Client (if you want to use the API in your own project)

OpenAPI GUI, an online editor for OpenAPI:

• https://github.com/Mermade/openapi-gui
• https://mermade.github.io/openapi-gui/

Reviewing changes to the YAML doc

If you're actively changing the openapi.yaml file locally it is best to use nodemon. If you've changed the documentation you will only need to refresh the browser, instead of restarting nodejs again. Run:

nodemon

Note: You'll find an openapi.json file as well in this source. It isn't used and only here for reference purposes.

Generate OpenAPI JSON and MD

Run the following command to generate the JSON and MD file in one go:

npm run generate

Note: You will need the following npm modules in order to run the generate script.

OpenAPI.yaml to OpenAPI.json

Use npm run openapi2json to create the JSON version of the OpenAPI documentation. It will create/overwrite the openapi.json file!

Uses a global js-yaml install:

npm install -g js-yaml

Reverse proxy

This solution contains a reverse proxy in order to circumvent the self-signed certificate the WiiM device uses.
The proxy can be found at http://localhost:3000/proxy/{command}.
For the internals, see the index.js file.
The reverse proxy will translate the command requested to the proper url that the WiiM device understands and return any output it receives.