RemoteControl Plugin: LocationService Error Message and Documentation Incorrectly Reference 'countrylist' Instead of Actual 'regionlist' Operation

[kutaibaa-akraa]

@gzotti, @alex-w, @10110111

I've identified a clear discrepancy in the RemoteControl plugin's LocationService between its implementation, its error messages, and the official documentation.

The Issue:

1. Incorrect Error Message: When sending a GET request to http://localhost:8090/api/location/ without an operation, the service returns:

   unsupported operation. GET: list, countrylist, planetlist, planetimage
   

   This message is generated from LocationService.cpp line 119.

2. Mismatched Implementation: The code actually implements the operation as regionlist, not countrylist. This can be verified in the same file (LocationService.cpp), where the regionlist operation is correctly defined and executed:

   else if(operation == "regionlist")
   {
       // ... implementation ...
   }

3. Documentation Error: The official API documentation (remoteControlApi.html) incorrectly states that countrylist is a valid GET operation for the LocationService, providing a description and expected return format for a non-existent endpoint:

   countrylist

   Returns the list of all known countries (StelLocaleMgr::getAllCountryNames), as a JSON array of objects...

4. Actual Behavior: The actual regionlist operation returns a well-structured JSON array of geographical and planetary regions, as demonstrated in the attached regionlist.json file. This confirms the operation is functional and provides valuable data.
   regionlist.json
   Steps to Reproduce:

5. Start Stellarium with RemoteControl plugin enabled.

6. Send a GET request to http://localhost:8090/api/location/ → Observe error message with countrylist.

7. Send a GET request to http://localhost:8090/api/location/countrylist → Returns an error.

8. Send a GET request to http://localhost:8090/api/location/regionlist → Returns a valid JSON list of regions.

Suggested Fixes:
To resolve this inconsistency, we need to align the code, error messages, and documentation. I see two possible approaches:

• Option 1 (Align Code with Documentation): Implement the countrylist operation as described in the docs (using StelLocaleMgr::getAllCountryNames) and update the error message to include it, while also keeping regionlist if it's still needed.
• Option 2 (Align Documentation with Code): Update the error message in LocationService.cpp to list regionlist instead of countrylist, and update the official documentation to reflect that the operation is regionlist and describe its actual output (as shown in the attached file). This seems the most straightforward fix, as regionlist is already functional.

Recommendation:
Given that regionlist is already implemented and working, Option 2 is the most practical solution. It avoids introducing a new feature and simply corrects the documentation and error message to reflect reality. This would prevent confusion for developers using the API.

Relevant Links:

• Code file: LocationService.cpp (See line 119)
• Documentation: remoteControlApi.html (See "LocationService operations" section)

What do you think is the best way to proceed?

---

[alex-w]

Oops… it should be regionlist of course! This is very sad, but apparently we forget updating RC plugin when Location class was changed.