Testing - What information should a story for an API contain?

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.

This might be a missing category:

2d) which combinations for parameters are possible?
E.g. gun violence can be a trigger for certain people.
Gun violence can be set on or off.
Only viewers older than 14 year can see movies with gun violence.

In this case the age of 16 and no gun violence is a valid combination.
The age of 8 and gun violence is an invalid combination.

In my experience the best examples are gathered using the Three Amigos. A tester, a business analyst, and a developer are talking about a story. Because of the different views and cooperation more examples are brought up.

1 Like