As a tester, I expect the following things to be provided in an story for an API, especially for a new API. Do you think these expectations are reasonable? If you have more expectations, then please share them.
1 - Examples of how the API works at a high level, preferably in the “given, when, then” format.
These can be considered as acceptance criteria. I need only basic examples of positive scenarios. Examples of some basic negative scenarios are nice to have. I can figure out the remaining, harder scenarios.
e.g.Given the user is logged in, When the user enters an age >= 18 for a violent video game, Then they should be allowed to play that violent video game. (I know this a silly feature, but its only for illustration here).
2 - Detailed API spec for the request and response parameters.
(2 a) Which params are required or optional, and their data types?
e.g. We like to keep age as string instead of integer. It is required.
(2 b) What are the valid and invalid values for each param?
e.g Age cannot be negative or more than 150.
(2 c) Which of the request params does the API compare with backend/databases?
e.g. The api only checks if Age is valid & meets business rules (i.e. user should be an adult). It does not look up the age in database. OTOH, the api compares the user id with the user information stored in our database.
Unfortunately, I never get all these things in one place/document/story. For example, the story has only (1), the swagger document has only (2 a), the developer code has (2 b) and only the developers know (2 c). For existing apis, if I am lucky, I might find QA team docs with (2 a) and (2 b). So, I have to talk to multiple people like the product manager, developers and QA to get a basic understanding of the API. IMO, having such crucial and basic information scattered like this is a huge waste of time for everyone.
Is it reasonable to expect (1), (2 a) and (2 b) to be provided only by the product manager in stories? I can ask the developers or product manager about (2 c).
PS -
I want proper division of responsibilities and set correct expectations. Some overlap in responsibilities is ok, but I can’t be doing other people’s work routinely.