CODEWITHSUNDEEP
javascriptjsonlaravelrestapi-design
akcoban
akcoban

Reputation: 973

RESTful api using array keys or array values for POST data

I building a RESTful api and I need to get complex data from front-end. But I am not sure which one should I choose for POST data.

I should get prices for all possible routes of route group. An example: There's a bus, that's starts from port-1 and goes to port-2 and ends on port-3. I should get price lists for every passenger type for routes:

port-1 to port-2
port-1 to port-3
port-2 to port-3

I thinking on the two options. You'll be understand the data type by looking at the sample data below.

1-

prices: [
    {
        departure_port_id: {value},
        arrival_port_id: {value},
        ticket_type_id: {value},
        priceable_type: {value},
        priceable_type_id: {value},
        price: {value},
        companion_price: {value},
    },
    {
        ...
    }
]

2-

prices: [
    {departure_port_id}-{arrival_port_id}: [
        {ticket_type_id}: [
            {priceable_type}: [
                {priceable_type_id}: {
                    price: {value},
                    companion_price: {value},
                }
            ]
        ]
    ]
]

I am not sure which one is better for front-end.

On the first one, that's looking clear but there're so much duplicate data and developer should manipulate data. Maybe can set data- attribute to input and should manipulate the data on the js side before submit.

On the second one, there's no duplicate data, all grouped by keys and it's useable for the input's name attribute. like: name="prices[1-2][1][passenger][1][price]"

What do you think about that? Or do you have better idea?

Upvotes: 2

Views: 1083

Answers (2)

k0pernikus
k0pernikus

Reputation: 66599

There is no right and wrong answer here, but it mostly boils down to trade-offs:

Is there a need to have these endpoint be fast, light on traffic, "easy" to work with? (Maybe it would even make sense to split this endpoint into a dedicated price/departurePortId/arrivalPortId endpoint.)

Depending on your use case, the redundant flat approach could also be better than the nested object, esp. if the need for the client arises to groupBy a different property as that is pretty straight-forward to achieve on a flat array. (Flattening a nested object can become a nightmare. I've been there.)

A big downside of the nested approach is that it hides meta-information, all these ids:

  • {departure_port_id}-{arrival_port_id}
  • {ticket_type_id}
  • {priceable_type}
  • {priceable_type_id}

are only used as their dynamic values as (combined) keys and if they are numeric, it becomes very hard to reason about their meaning. If you were to see such a response, you deal with magic numbers and have to know their intent. So if you were to go with the nested approach, I'd still keep all the data in the final object.

Another downside of dynamic keys is that they are hard to express in a lot of libraries providing api documentation. (E.g. swagger has problems expressing the idea of an dynamic key and if you want to add that, you may have to redefine your model then.)

With that being said: I'd go for the flattened response. It may depend on your use case.

I opt for one change though, and that is grouping relevant information:

prices: [
    {
        ports: {
            arrival: {id: $value},
            departure: {id: $value},
        }
        ticket: {
            id: $value,
            type: $value,
        }
        priceable: {
            id: $value,
            type: $value
        },
        price: {
             amount: $value
        },
        companion_price: {
             amount: $value
        },
    }
]

The downside of only having primitive values is that it becomes hard to change / add new fields. And on entire flat objects the information can become cumbersome to parse. (Assume you also want to add the name of the port or the currency of the prices. Assume you have different currencies for different pricing information. A complete flat response could become a naming hell, i.e.: departure_port_name, arrival_port_name, companion_price_currency).

Upvotes: 2

Kirill Kikimov
Kirill Kikimov

Reputation: 14

i think first case is best. You may look at https://redux.js.org/recipes/structuring-reducers/normalizing-state-shape .

Upvotes: -1

Related Questions