search

StevenWeathers / thunderdome-planning-poker

⚡ Thunderdome is an open source agile planning poker, sprint retro, and story mapping tool
https://thunderdome.dev
Apache License 2.0
421 stars 109 forks source link

[Bug]: Poker story objects in API have different syntax depending on endpoint #644

Open heinezen opened 2 weeks ago

heinezen commented 2 weeks ago

Contact Details

No response

What happened?

I'm not sure if this is exactly a bug, but it's definitely annoying. Depending on which endpoint in the API is used, poker stories are expected to have a slightly different format. In my case, I was confused by the different schemas for poker stories used in the endpoints

  1. POST /users/{userId}/battles (creating a new poker game)
  2. POST /battles/{battleId}/plans (adding a poker story to a game)

The 1. endpoint expects the schema of the http.battleRequestBody object for the game, which refers to thunderdome.Story for the poker story object. 2. expects a different schema called http.planRequestBody.

Not only is the schema different, the naming of the fields in these schemas are also not consistent. For example, setting the poker story title in thunderdome.Story uses the field name, while it's planName in http.planRequestBody. There are also some fields that are not specified in the schema of http.planRequestBody but are apparently still parsed and processed, e.g. priority.

Self Hosted?

No

Version

Latest

What browsers are you seeing the problem on?

No response

Relevant log output

No response

Code of Conduct

StevenWeathers commented 2 weeks ago

Thanks for pointing out these discrepancies, unfortunately without breaking the API I can't correct name differences, however I can add non required fields to the API docs.

StevenWeathers commented 2 weeks ago

I've added priority to the story create request body, when I do a v5 I will try to reconcile name discrepancies.

heinezen commented 2 weeks ago

I can understand that you don't want to break the API. Maybe it would be possible to check if the received JSON data contains unrecognized fields? I spent a mildly frustrating amount of time on figuring out why passing name to POST /battles/{battleId}/plans wouldn't set the title of the story correctly, only to find out later that planName was correct :smile: Pointing out that the data contains unrecognized fields may allow people to catch these problems sooner.

StevenWeathers commented 2 weeks ago

API Validation responses is something I do need to improve, it can be confusing which field failed validation currently.