Tables are easier to understand than REST + JSON
Choose SQL
Given the choice between a SQL interface or a REST interface to the same state, I think developers should prefer the SQL one.
SQL GUI's allow you to browse actual datasets and values. The fact that values are listed vertically down, allowing you visually scan with your eyes, allows you to infer the meaning of that data. Any questions about those values that arise can be answered with an introspective SQL query, directly run in the GUI.
By contrast, a REST API will just tell you about the types, and perhaps give you a single example value.
Whilst the example is useful, in practise these types contain a large tree structure of values, many of which are irrelevant to your current line of enquiry, or are empty/default values. With a single example value it is hard to determine the meaning. With SQL, you are viewing the values of a specific type in the context of the whole dataset, so the meaning is obvious.
The fact that JSON-like tree types can have branches which are optional or can be multiple types (Related: Polymorphic types, Tagged unions, Duck typing) makes it extremely difficult for the developer to understand the meaning of those types using documentation or dynamic languages. Strongly typed languages help here as the IDE can tell you what the set of possible types are - but type systems cannot always represent the meaning of the highly dynamic JSON types, and you are still being told about a single type rather than a value in the context of a dataset.
Whilst SQL does not handle "can-be-one-of-many-types" very well either, if each of those possible types has it's own table, and you can use SQL queries to form your own result sets, it becomes easier for the developer.
Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious.
Fred Brooks
Flowcharts = REST API documentation
Rest API's are necessary
It is necessary for SaaS API's to provide a network based API as this allows:
- Security access control logic.
- Strongly typed public interfaces, which can be versioned.
REST API's are often thin proxies wrapping SQL databases - it would often be easier to read the SQL database directly, rather than go through the proxy which deliberately limits which actions you can take, and how fast you can read your data.
Convert your REST API to a SQL interface
The tdog CLI continuously downloads your Stripe account to a SQL database allowing you to leverage the benefits of SQL.
Try tdog for free against a Stripe test account