How to (and how not to) design REST APIs • Hacker News Board

Re: How to (and how not to) design REST APIs

#151

Post by jasmataz » Fri, Nov 03, 2023, 10:26 PM UTC

I'm curious about your thoughts on omitting properties vs. setting them to `null` for a public facing API. I'm especially curious about your feelings on mixing and matching these strategies. Should you always stick to one strategy or is it ok to sometimes omit and sometimes use null to express the same idea that "the data is missing"?

An example of a null property:

    {
        "firstName": "John",
        "middleInitial": null,
        "lastName": "Doe"
    }

Compared to the omission of the property:

    {
        "firstName": "John",
        "lastName": "Doe"
    }

Essentially the idea discussed in this Stack Exchange post (ignoring the use of empty strings as an option): https://softwareengineering.stackexchange.com/questions/3437...

Re: How to (and how not to) design REST APIs

#152

Post by kennu » Fri, Nov 03, 2023, 10:29 PM UTC

3cats-in-a-coat wrote: post #150

kennu wrote: post #148

Earlier quoted context omitted.

My point about arrays vs maps is based on the idea that you store the data in e.g. DynamoDB as the same structure as it is represented in the API. If you store an array in an attribute of the database item, you cannot update its contents in an idempotent way. Inserting or appending to the array multiple times (using the relevant DynamoDB functions) causes it to grow more and more each time. Whereas when you use a map…

OK but transfer format and working representation shouldn't be the same. That is a bad goal to have. A working representation is sparse, indexed, you can jump to places and change parts. While input (and output) are streams of dense data. Adding redundancy to input/output so you don't have to make local decisions for your working representation may seem like a simplification, but you're basically chaining yourself fr…

To me it's a good goal. I want to keep things simple and minimize my work. It works very well with a document database like DynamoDB. Even if often there is a small translation going on, removing a few attributes or adding a few to achieve backward compatibility, but mostly passing them 1:1.

Re: How to (and how not to) design REST APIs

#153

Post by 3cats-in-a-coat » Sun, Nov 05, 2023, 12:48 AM UTC

kennu wrote: post #152

3cats-in-a-coat wrote: post #150

Earlier quoted context omitted.

OK but transfer format and working representation shouldn't be the same. That is a bad goal to have. A working representation is sparse, indexed, you can jump to places and change parts. While input (and output) are streams of dense data. Adding redundancy to input/output so you don't have to make local decisions for your working representation may seem like a simplification, but you're basically chaining yourself fr…

To me it's a good goal. I want to keep things simple and minimize my work. It works very well with a document database like DynamoDB. Even if often there is a small translation going on, removing a few attributes or adding a few to achieve backward compatibility, but mostly passing them 1:1.

We have the same goal. I'm just saying that what's simple for local representation complexifies the transfer format, and what's simple for transfer bogs down the local representation.

Essentially we're discussing the cohesiveness vs decoupling of a transfer format and local representation. But purely on the objective side I have one strong argument: the transfer format of HTTP-based APIs is designed to be client neutral. It won't be just JS in the browser. It may be Swift on the Phone or .NET on a laptop.

And so coupling tightly transfer with a specific client can be a good choice only in the narrow scenario where you control both API, client, and there's no another client. You can always extract more of such a scenario. For example you may not use JSON at all, you can use a custom binary format that directly dumps whatever you want in your app.

But in the general scenario where the API is an API, and the client is a client, what I said stands.