Fork me on GitHub

I want my api to return a json with strong names out of instinct but my coworker requests small names. What do you usually do in that situation?

💯 1

Measure the difference in practice, see if the distinction is meaningful enough for everyone.

Geoffrey Gaillard09:01:23

What are examples of strong vs small names?


"" vs "replies"

👍 1
Geoffrey Gaillard10:01:29

I side with Aron. what is the use case for small names ?


I think the only point if favor is that it's more familiar My coworker brought up memory size but I that's probably silly. It's just a few hundred entries

Martynas M10:01:19

Let's say you want to translate text in the front-end. Is it easier to map the long value into text or the short one?

{"result": "ok"}
Or this?
{"result": "com.greed-bank.incoming.payment.ok"}


the short one

Martynas M10:01:55

I would consider whether your system will always return the result right away or return data later. Also I'd consider if you will open the API ever. Because if you will return the result with the short version then you will only be able to process that data right away and only in that specific circumstance. Whereas if you will want to return the longer version you will be able to provide output for the user more flexibly.

💯 1
Martynas M10:01:04

i.e. if you'll return only the ok then it may mean sense if you expect it to act as HTTP 200 . But if you want rich errors then it may not suit you.

👍 1
Martynas M10:01:57

But that's only about values. I don't know about keywords/names. Maybe other people will give more info :))

Martynas M10:01:04

Because I made an assumption that you wanted to use your data like this:

{"data": ""}
But maybe you want to use it like this:
{"": [1, 2, 3, 4]}
{"replies": [1, 2, 3, 4]}
Then I would try to understand whether you want to merge the results from multiple "domains" into one response:
{"": 5,
 "": 195,
 "com.example.corp.number": 42}

Geoffrey Gaillard10:01:54

Memory size is a fuzzy argument without metrics. By default, I’d go with the most explicit, and map it to less explicit if needed. Mapping from strong names to small is injective. The opposite is not. In the general case, strong names are context-free, small names are ambiguous.

clojure-spin 1
👍 1

I was thinking about key names yea. Atm there wouldn't be anything that merges the map with anything. It just seems more robust to me if that is a possibility


googlelin "injective" now

Martynas M10:01:17

@U2DART3HA Let's say I have two names: namespace-1/a and namespace-2/a . If I map into small names then I would get a in both cases. And your link says that injective value should map into two distinct values. Which in my example wouldn't work because it would behave as "Surjective", because you lose information. So I think what you wanted to suggest is to use fully qualified names to be able to have injective style of conversion later. But the conversion itself is not (may not be) injective. Is this correct?

Geoffrey Gaillard10:01:06

Thank you for noticing my unintended BS. I think you are correct. `Mapping from strong names to small is injective` This is wrong. What I should have said: Mapping from strong names to small can be made injective in the general case.

Martynas M10:01:05

It's new for me 😄 I see we're all learning here 😄

Geoffrey Gaillard10:01:31

because you lose information. This is the bottom line, I think. You want to provide as much info as possible, allowing your future self/coworker to remove the unnecessary bits. Me today: is too long 🦥 Me tomorrow: What is this a? :thinking_face: YMMV

💯 2

it's easier to write spec for something more specific. But if you don't use constraints, better don't have many versions of a around 😄

👍 1

since strong names don't have specific syntactic support in js, they're not quite a thing in the ecosystem. so it will be you vs. almost every frontend developer ever 😄 I'd look into having either of these as a middle ground: • having an http middleware in the js client that shortens names, if they belong to a whitelist ◦ i.e. they review/update the whitelist regularly • returning short names from backend, but making sure to not ever change semantics

📝 1
Martynas M15:01:50

I think we should all agree on the logical conclusion out of that single point of data: The worse it becomes to front-end guys, the more understandable the system becomes over time. Therefore we should strive to make their lives worse.

🙂 1

ask why {u: {n: "Hello"}} isn't better than {user{name: "Hello"}}

✔️ 2

For JSON REST APIs I like to keep the keys simple, and prefer JSON structure to disambiguate values (e.g. {"foo": {"a": 1}, "bar": {"a": 2}}). That way there's a clear boundary between internal representation of data, and its representation in transit. In general a system should define, at the boundaries, how data is modeled internally. Leaking (e.g.) namespace names in keys is, well, leaky.


BTW, I already handled a frontend team that requested unmeaning key names, and send me back these keys too I developed this library to handle this kind of problem:

❤️ 1