Currently, I'm designing the intended operation of a (RESTful) API which a team of developers will eventually build. I'm not concerned with implementation details, as long as inputs are correctly mapped to outputs (and data in the database won't be messed up :-)). To me it's not important whether it's built in an OOP or FP manner for example.
The problem: communicating the intended inner workings / business logic of the API in such a way that business people can understand what's going on (and hopefully provide feedback), and that developers will be able to write stuff that does what it's supposed to. So, it needs to be fairly abstract but still needs to contain enough detail for the developers.
The specs are primarily intended to be consumed by the devs. Business people should be able to understand them, but it's crucial that they contain enough information for the devs to start building.
By all means, I guess it makes sense to describe each user interaction (or API endpoint) separately. They could be described in roughly the following format:
- Description (e.g. 'creating a user account')
- Input parameters (data to be provided by the user, e.g. 'name', 'e-mail' and 'password')
- Process (some sort of representation of the inner workings and outcome(s))
Makes sense? Am I missing important stuff here?
What would be the most suitable format to represent the process?
Pseudocode won't make too much sense to the business people. Automated tests will be written (and used by the devs) but the business folks won't read them.
Currently, I'm leaning towards flowcharts. They're visual in nature, easy enough to understand when done well and able to contain the required amount of detail (such as conditionals). It's possible to refer to the entities and attributes of the ERD that will be stored in Confluence (our documentation system) as well. Annotations can be used to provide additional (technical) detail.
Is this a reasonable approach? Are flowcharts a decent solution in this situation? Any better options?