undefined | Better HN

0 pointssystemvoltage5y ago0 comments

I am opionated about this, I am sure people can share other perspectives.

When you're operating a CNC machine, as an operator, do you need mess around with internal wiring, schematic, motor controllers? No. You just need a control panel, with DRO and a bunch of buttons, a joystick for manual override, e-stop and a keypad. You're not dealing with the exposed wiring and internals of the machine. Nor do you care (except if you're a hacker, more on this below).

APIs are all things the user needs to do and we allow them specific endpoints to do those things. A lot of modern GraphQL methods allow you to become a "hacker" and get access to what you want. But, after you're done hacking, you want a proper control panel with steel panels and a version number. You, as a user, are guaranteed that interface and you're going to build your world around it. Check out Shopify, Stripe or Dropbox APIs. See what they allow you to do and what they don't.

Here are some reasons why we want an API:

- Decoupling internal resources from the user (user can still be an internal service). We want to be able to change the database, swap it with anything else we want, completely change the schema, whatever... without affecting the user.

- We might require processing/handling of the data, sometimes with help from other microservices before serving.

- We might want to cache read access, although I am sure this is possible with these automation tools.

- We want stability over expediency (although, this is ok to forego initially).

- We want a singular point of entry, aka entrypoint and be able to control it.

- We might want to asychorniously process the request. "Hey, I got your request and I am processing, here is the processing ID" and respond with status code 202.

All these automation tools are great to get a product running quickly. Personally, I would just use straight SQL for prototyping. If you're working on UIs and don't have access to the server, you can just use https://postgrest.org/ and get an API running. However, after you're product has reached maturity, tighten up those endpoints.

The endpoint design is your control panel. Make it look tidy, checkout how others build this panel, engineer it well and your users will thank you.

0 comments

oAlbe5y ago

Do you happen to have any resources for learning more about API design in the way you described it? I'm really interested to learn more.

Your comment was very insightful. I used to think somewhat along those lines when it came to designing an API. My thought was that and endpoint was to represent an action the user could perform, and it was none of their business how that was implemented. But I've recently been enlisted in a project to rewrite a whole API (admittedly not a good one at all) where it was decided to use GraphQL. The rationale was "some of our endpoints return enormous objects. Not all of the data is needed every time the client calls that endpoint. Let's implement a way to let the client only ask for the data it needs". It sounded great, but I'm thinking now it might not be all gold as it was presented to me.

mohbk5y ago

you can solve underfetching and overfetching in a normal restful API, you can have optional entity relationship fetching on query/params, and also user defined queries.

This might be hard/tiresome when you're hand writing SQL queries but this is where query builders and ORMs really shine.

IMO I wouldn't reach for graphQL unless I have a lot of entities and a lot of nested relationships (or an actual graph), it can get either very tiresome to add or overly complex or tightly couples your DB layer when you have deeper nested relationships

derangedHorse5y ago

Having the client able to dynamically ask for data from models sounds like a horrible idea to me (if I’m understanding correctly). I once had to work with someone who used the Open Data protocol to make an API with a similar approach and hated it because it felt like query writing was moved from him, the backend engineer at the time, to time the front end engineer. In addition to that, the way he did it could have lead to data we didn’t want exposed to be leaked easily by mistake

j / k navigate · click thread line to collapse