I would like to be able to describe declaratively the rules that describe what constitutes a valid input into my API. So that I could express things such as “when X is provided, Y also needs to be provided” or “A and B are mutually exclusive”. I want this to be declarative, to be data, so that it could more easily become a part of the documentation and the users of the API could use it themselves to verify what they want to send.
Currently the REST API has Swagger / OpenAPI docs. These specify the data types of the inputs but only a (small) subset of all the possible values that satisfy the types are actually valid. There are important business rules that further limit this domain but they are not communicated. At best there are some comments that mention some of the rules. Thus the process of developing with the API consists of trial and error, sending requests the developer things are right, trying to interpret the error messages, frequently reaching out to the developers of the API for clarification, correcting the requests, and so on. Not very efficient. What it we could make those rules explicit and include them in the documentation? And preferably make them available to the clients so that they could use them in a programatic way?
NOTE: Some of the rules could be encoded with a smart use of data types such as union data types (e.g. “the product user is either Person or Role”).
To make it concrete, here are a few examples of rules from my domain, ordering of mobile subscriptions and phones:
If the user already has a subscription and should pay breakage fee then her consent to that may be provided. In all other cases it must not be present.
If the order includes a SIM card or any hardware then delivery information must be provided.
If the order only includes a SIM card then the delivery method may be “letter”.
If the product user is a person then we also need her address. (Note: this could be encoded in the data types but currently is not.)
If the order is a transfer of a phone number from a different operator then a consent by the donor legal owner must be provided. However the order can be created without it, it is only required when submitting it.
Does this reasonable? And doable? How do other people solve this problem, through a better documentation?