Ask HN: Does generic API increases productivity or decreases it? | Hacker News Reader

Ask HN: Does generic API increases productivity or decreases it?

1 pointthrowaw128 comments

Imagine you are building an API and you are thinking if you should make it generic or use case tailored. From your experience, did generic API increase your productivity and happiness or lowered?

Example scenario:

    Generic: Organization
    API: /organizations

When you fetch data result contains generic data about organization, its type and type associated data. For example, if Organization is of type Developer (in construction). It can give you their license number, some statistics about their performance

    Non-generic: Agency, Supplier, Developer (construction), ISP Provider
    APIs: /agencies, /isp_providers, /developers, /suppliers

Each will repeat some set of querying patterns, like searching by name, but also might have use case tailored parameters, for example for ISP providers you want to find providers by their bandwidth.

Which API you would prefer?

View on HN

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.

These are good observations, thank you!

> 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).

At the moment, I don't know if we will expand to the second use case. Because scope is limited and data set is also limited (mostly contains generic data).

I think in that case it might make sense to go with option 1 and eventually introduce v2 which covers option 2.

I would rather implement a generic list that contains only common attributes, type and then an url that points to /agencies/:id . /agencies and the others are in this case aliiases for an fikter on /organizations if possible.

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".

I love HATEOS style APIs as a user, but not as a developer building them. Because they're not trivial to build and creates a lot of coupling between systems.

For example, if I have a device, which belongs to organization, HATEOS advises me to include a link to `organization` object and how to get there.

But, if I am writing a microservice for devices or any other isolated logic from organizations model and how organizations model is exposed externally. Now I need to create coupling between 2 systems and know how to address owner `organization`.

> For example, if I have a device, which belongs to organization, HATEOS advises me to include a link to `organization` object and how to get there.

If it is a general purpose interface, you probably want at least one representation of devices that exposes the organization.

You may also want one that doesn’t, and you may not want any that do. There’s no violation of HATEOAS in having collections that link to leaf nodes but leaf nodes not linking to collections they may be part of.

All HATEOAS really says is that if you want clients to be able to get from the device to the owning organization, then you should include a link to the organization in the representation of the device rather than relying on the client interpreting the structure of the URI of the device to infer the associated organization.

Hypertext as the engine of application state does not have strong opinions on what navigation or state transitions are supported, only that those that are supported should be supported via hypermedia techniques of in-representation locators for location, methods with well-defined semantics operating against the resources at those locations, and representation types (e.g., media types), with each serving its particular purpose.

regarding your other point about limitations of how statically typed languages parse data. How about making this kind of response:

    class Organization:
        id: string
        name: string
        ... couple of common fields ...
        supplier: Supplier # supplier specific fields
        agency: Agency # agency specific fields
        ....

So, yes, one can view SQL as one of these languages that has trouble with sum types and a faithful representation of a tagged sum in SQL is

    Either Supplier Agency
      <-->
    CREATE TABLE supplier_or_agency (
      id UUID PRIMARY KEY,
      supplier_id UUID,
      agency_id UUID
    );
    ALTER TABLE supplier_or_agency 
      ADD CONSTRAINT only_one_null
      CHECK (
 CASE WHEN supplier_id IS NULL 
             THEN agency_id IS NOT NULL 
             ELSE agency_id IS NULL
        END);

And this sort of convention can be carried over to Java, where after all these are just pointers...

    class SupplierOrAgency {
      private final Supplier supplier;
      private final Agency agency;
      private SupplierOrAgency(Supplier s, Agency a) {
        supplier = s;
        agency = a;
      }
      public static of(@NonNull Supplier s) {
        return new SupplierOrAgency(s, null);
      }
      public static of(@NonNull Agency a) {
        return new SupplierOrAgency(null, a);
      }
      // Add getters and maybe an enum I guess?
    }

And yes then you get an approach like that.

The basic problem for interpretability is that you get annoying questions about "what if the API that I am consuming violates their contract” or maybe even “TypeScript can't figure out that because these two are null it must be that that one is not null” or some similar crap.

The truth is, in SQL databases this never comes up. So the only reason that you are doing this is that you want to have a collection that contains both data types, and in SQL such a collection is a record that exists in some table, membership in that collection is by other things pointing at the collection. This makes it effortless to just have two collections on the same record, one of agencies and one of suppliers.

Similarly in Java, instead of

    public Foo {
       @NonNull public List<SupplierOrAgency> resources;
    }

It makes more sense from a type safety perspective to just have two collections,

    public Foo {
        @NonNull public List<Supplier> suppliers;
        @NonNull public List<Agency> agencies;
    }

Reply on news.ycombinator.com