API endpoint states matter more than schemasFoundation series - Tenet 3

Another widespread idea in the API industry also is the preeminence of schema. Look at any API documentation, chance is high that you will get to the very fine details about JSON or XML schema: the type of an attribute, the set of attributes, a few examples and so on.

Take a payment processing API for example: they typically expose a payment authorization and capture endpoint where you input a credit card number (and it's beautifully written that a card number is a `string` of digits in groups of 4 with space, or just 16 digits `number`) and you get a result. Then you will be given a list of test card numbers, one per outcome: a successful payment, a failed payment, an insufficient fund payment error, etc.

That is fine for a specific usage: automated testing, just like we said in the tenet 2. The real world is richer than that in terms of context.As a payment API consumer, I want to be able to know FORMALLY the endpoint STATES instead. I want to know that this authorization endpoint has these state: [200, :success], [404, :card_not_exists], [401, :card_not_allowed_by_card_company], [500, :network_error_while_calling_a_third_party_system_so_please_retry], [500, :another_type_of_error_where_retrying_does_not_make_a_difference]...

... and I'm interested to know all these upfront, and to be able to activate each of these states in a flip because they all translate in terms of UI and behavior in my application. I want to flip back and forth effortlessly between these states regardless of the card number I input when I develop, I want focus on my app behavior in the middle of a mix of API endpoints calls I make between potentially many providers, and potentially where I cannot explicitly change the card number value in the middle of an orchestrated interaction. I don't want in that context for example, to hit another obscure card number format validation that derails my current interaction design, even if I entered 1 or X as card number value: I want to be freed from the schema constraints and embrace states freedom.