Does generic API increases productivity or decreases it?

What I'm looking for in an API is convention and some common set of rules. As long as the API has an understandable structure and good documentation, I'm happy.

The first case would be preferred if the API is for e.g. general queries of companies in some region. The second case might be preferred if your API only deals with those specific companies and has a different structure for each one (for good reasons).

You can also provide both APIs - one for general data, and one for specific details.

So a programming language like Java really doesn't handle sum types (the first example you give) all that well. It's getting better but it's not all there yet. If you expect those languages to consume then you want the second version.

What I really want is a sort of HATEOAS JSON approach where under some /.well-known/ URL we all agree to serve the data model of the web site -- what I mean is that, if the protocol is called "fairyland" for instance, you access /.well-known/fairyland-schema and you get something back like

    {
        "fairyland": "v1.0", // schema version
        "apiVersion": "1.0.0", // your API version
        "auth": [{
            "type": "oauth2",
            "login": "https://.../"
        }],
        "featureFlags": {
            "redis_agencies": {
                "description": "Queries for agencies are cached by Redis, making them eventually consistent.",
                "rollout": 0
            }
        },
        "entrypoint": {
          // ...
        },
        "types": {
            "Agency": {
                "properties": {
                    "id": {"type": "text", "regex": "some-uuid-regex"},
                    "license_number": {"type": "text"}
                },
                "actions": [{
                    "GetSuppliers": {
                        "description": "Gets the suppliers associated with this agency",
                        "action": "GET",
                        "urlParams": {
                            "activeOnly": {
                                "description": "Include only active suppliers?",
                                "type": "enum",
                                "values": ["true", "false"]
                                "default": "true"
                             }
                        }
                   // ...

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:

1. doing the auth handshake, then making requests starting from the entrypoint,

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,

3. when you would get back a type=Agency object, if it had an actions section looking like,

    "actions": { "GetSuppliers": "https://api.example.com/v1/suppliers?agencyId=12345" }

then the client would reference that against the already-downloaded actions list and say "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 `&activeOnly=false` param to get the inactive suppliers for that agency as well."

It'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's how we do auth here... it'd be nice to just specify one approach with a HATEOAS flavor of "each resource can have actions which are links to URLs that specify other resources".