How should we document or specify the Bose servers API?

[gmuth]

The goal of soundcork is to implement the Bose servers APIs. Until May 2026 we can analyze behavior and capture communication. This includes successful and failing requests. Different ways are currently in use to more or less document the API:

• API_Spec.md committed by @deborahgu
• Use case related issues like #97 Add device
• Implementation code like GET /bmx/registry/v1/services committed by @akpdw
• Ueberboese uses openapi 3.0 provided by @julius-d (another project)

Another approach would be to implement unit or integration tests which successfully run against the official Bose cloud. Than we could switch the system under test to soundcork and validate its behavior automated. This could be the place to make issues like #167 reproducible.

To test APIs developers use tools like

• curl
• Bruno
• HttpClient

However those collections usually only cover the requests

[gesellix]

Another variant: I'm already collecting interactions in .http format, which includes the complete request and response with all headers. To go even a step further, I started intercepting DNS lookups to collect host names we might not be aware of (gesellix/Bose-SoundTouch#58)
All logs can be analyzed in a small web ui, filtered by an attribute to find requests passed to the upstream Bose servers (so not already handled by ourselves). Maybe you're interested in such traces here in the Soundcork service. I could help with that or port my Golang impl to Python, but I have to say in advance that it will be 80% AI generated (code review by myself before creating a pull request here).
What do you think?

[gmuth]

I also like the .http format using IntelliJs HttpClient. This covers only the request - I guess you just copy the response to another location. Could please provide a link to where you document the Bose API calls? Secrets placed in http-client.private.env.json are usually not committed. I'd like to focus on HTTP for this discussion.

[gesellix]

Responses are added as comment into those files (I need to check, I missed some request bodies, but at least the response was definitely saved).
Extraction of some patterns is already prepared (e.g. for deviceId, account if, IP address), but I have to find all patterns for tokens and such so that they are also extracted to config files.

[gesellix]

I'll provide an example after returning from the carnival parade ;)

[gesellix]

An example .http file looks like below. Pattern extraction for tokens and other user specific variables will be the next step to ease sharing with other people. I manually replaced such values in the example.

### POST https://streaming.bose.com/streaming/account/.../device/---/recent
POST https://streaming.bose.com/streaming/account/.../device/---/recent
Host: streaming.bose.com
Content-Type: application/vnd.bose.streaming-v1.2+xml
X-Forwarded-For: 192.168.178.111
Content-Length: 307
User-Agent: Bose_Lisa/27.0.6
Accept: application/vnd.bose.streaming-v1.2+xml
Authorization: Bearer xyz

<?xml version="1.0" encoding="UTF-8" ?><recent><lastplayedat>2026-02-16T20:17:36+00:00</lastplayedat><sourceid>10863533</sourceid><name>Pleased To Meet You</name><location>/playback/container/c3BvdGlmeTphbGJ1bTozMVJoNkFiOHhDNDlmV2pGY3V5WEFL</location><contentItemType>tracklisturl</contentItemType></recent>

> {%
    // Response: 201 Created
    // Headers:
    // X-Amz-Cf-Pop: DUS51-P6
    // Access-Control-Allow-Origin: *
    // Via: 1.1 ea9e1c25c0938d08fa53a97cac11d952.cloudfront.net (CloudFront)
    // X-Proxy-Origin: upstream
    // X-Amz-Cf-Id: aD5HkSp6F_MkOgPkoTRTGZDrg6owOqHEsQZ2BtrkU9hYzDhppPoetA==
    // Date: Mon, 16 Feb 2026 20:17:40 GMT
    // Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization
    // Server: nginx/1.12.2
    // Location: http://streamingqa.bose.com/account/.../device/---/recent/2566960098
    // Content-Type: application/vnd.bose.streaming-v1.2+xml
    // Access-Control-Expose-Headers: Credentials
    // Access-Control-Allow-Methods: GET, POST, OPTIONS
    // X-Cache: Miss from cloudfront
%}

/*
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><recent id="2566960098"><contentItemType>tracklisturl</contentItemType><createdOn>2026-02-15T17:17:46.000+00:00</createdOn><lastplayedat>2026-02-16T20:17:36.000+00:00</lastplayedat><location>/playback/container/c3BvdGlmeTphbGJ1bTozMVJoNkFiOHhDNDlmV2pGY3V5WEFL</location><name>Pleased To Meet You</name><source id="10863533" type="Audio"><createdOn>2016-01-06T08:52:04.000+00:00</createdOn><credential type="token_version_3">___</credential><name>nnn</name><sourceproviderid>15</sourceproviderid><sourcename>nnn</sourcename><sourceSettings/><updatedOn>2020-04-25T20:29:11.000+00:00</updatedOn><username>nnn</username></source><sourceid>10863533</sourceid><updatedOn>2026-02-16T20:17:40.080+00:00</updatedOn></recent>
*/

[gesellix]

The web ui I mentioned looks like this, listing all requests, in this case filtered by all cases we didn't handle ourselves and to pass on the the upstream Bose services:

DNS lookup collection is also working now.... after an intermediate oopsie where I had to reset the firmware 😬

[gesellix]

However those collections usually only cover the requests

Jetbrains' HttpClient allows assertions/tests, which might help us to describe expected requests and response matching. It is even possible to perform such tests in CI, using their containerized http-client https://hub.docker.com/r/jetbrains/intellij-http-client