Ask HN: Does generic API increases productivity or decreases it?
So a programming language like Java really doesn&#x27;t handle sum types (the first example you give) all that well. It&#x27;s getting better but it&#x27;s not all there yet. If you expect those languages to consume then you want the second version.<p>What I really want is a sort of HATEOAS JSON approach where under some &#x2F;.well-known&#x2F; URL we all agree to serve the data model of the web site -- what I mean is that, if the protocol is called &quot;fairyland&quot; for instance, you access &#x2F;.well-known&#x2F;fairyland-schema and you get something back like<p><pre><code>    {
        &quot;fairyland&quot;: &quot;v1.0&quot;, &#x2F;&#x2F; schema version
        &quot;apiVersion&quot;: &quot;1.0.0&quot;, &#x2F;&#x2F; your API version
        &quot;auth&quot;: [{
            &quot;type&quot;: &quot;oauth2&quot;,
            &quot;login&quot;: &quot;https:&#x2F;&#x2F;...&#x2F;&quot;
        }],
        &quot;featureFlags&quot;: {
            &quot;redis_agencies&quot;: {
                &quot;description&quot;: &quot;Queries for agencies are cached by Redis, making them eventually consistent.&quot;,
                &quot;rollout&quot;: 0
            }
        },
        &quot;entrypoint&quot;: {
          &#x2F;&#x2F; ...
        },
        &quot;types&quot;: {
            &quot;Agency&quot;: {
                &quot;properties&quot;: {
                    &quot;id&quot;: {&quot;type&quot;: &quot;text&quot;, &quot;regex&quot;: &quot;some-uuid-regex&quot;},
                    &quot;license_number&quot;: {&quot;type&quot;: &quot;text&quot;}
                },
                &quot;actions&quot;: [{
                    &quot;GetSuppliers&quot;: {
                        &quot;description&quot;: &quot;Gets the suppliers associated with this agency&quot;,
                        &quot;action&quot;: &quot;GET&quot;,
                        &quot;urlParams&quot;: {
                            &quot;activeOnly&quot;: {
                                &quot;description&quot;: &quot;Include only active suppliers?&quot;,
                                &quot;type&quot;: &quot;enum&quot;,
                                &quot;values&quot;: [&quot;true&quot;, &quot;false&quot;]
                                &quot;default&quot;: &quot;true&quot;
                             }
                        }
                   &#x2F;&#x2F; ...
</code></pre>
so the idea is that you could fetch the well-known URL and actually generate a working, crappy little UI website which would browse that API directly. The client would take care of:<p>1. doing the auth handshake, then making requests starting from the entrypoint,<p>2. showing a little panel where you could toggle the available feature flags, the protocol would have some X-Fairytale-Features: header that would send these to the backend,<p>3. when you would get back a type=Agency object, if it had an actions section looking like,<p><pre><code>    &quot;actions&quot;: { &quot;GetSuppliers&quot;: &quot;https:&#x2F;&#x2F;api.example.com&#x2F;v1&#x2F;suppliers?agencyId=12345&quot; }
</code></pre>
then the client would reference that against the already-downloaded actions list and say &quot;aha, I know that I just need to make an HTTP GET request to that URL to get the suppliers, and I know that I can tack on an `&amp;activeOnly=false` param to get the inactive suppliers for that agency as well.&quot;<p>It&#x27;s a bit of a pipe dream but I keep seeing companies invent completely inconsistent or ad-hoc ways of doing feature flags, relating one request to another, here&#x27;s how we do auth here... it&#x27;d be nice to just specify one approach with a HATEOAS flavor of &quot;each resource can have actions which are links to URLs that specify other resources&quot;.