0

I'm currently designing my first API and I had a question: Should an API return all information about an object and its foreign keys?

To explain the above a bit better, this is a part of the database I have made:

DB

When I get a single event and I know that the person making the request needs the information about Event Location and Zone, should the API return the full information in one request, or should the person calling the API have to make a second and then third API call to get the remaining information about Event Location and Zone?

Thanks for any replies! If any further details are needed let me know :)

Improve this question
4
  • 3
    There is no right answer to this. Ask your consumers what they want. Will they always/sometimes/rarely need the additional fields? Whats the overhead on the response time and response size for including the additional fields? Do you have the bandwidth or desire to build/maintain multiple apis? You could build two endpoints, one for just event, one with evetything (not particularly RESTful, but if it meets the consumer needs..). So many ways to chop this up. Figure out the consumer's requirements by priority, figure out your own priorities and come to a decision/compramise.
    – K Mo
    Commented Mar 1, 2020 at 11:24
  • 1
    "I know that the person making the request needs the information" -- if can you tell this, then why would you force the person to make multiple calls?
    – Erik Eidt
    Commented Mar 1, 2020 at 12:32
  • 1
    Over the network, generally prefer to transfer data in a coarse grained way (more data at once), as the cost of making the call can accumulate over multiple calls and outweigh the cost of transfer (higher overall latency). However, take into consideration what data they actually need and when, under what scenarios, how are they going to use it (access patterns), consider paging, etc., and organize the API around that. It's a bit of a balancing act.
    – Filip Milovanović
    Commented Mar 1, 2020 at 14:33
  • To add to the other comments, the objects that you transmit over your API should be driven by the requirements of your API consumers, not how you happen to currently store the required information in your database. It is entirely valid to send an object that is built from information that is stored across multiple database tables.
    – Bart van Ingen Schenau
    Commented Mar 2, 2020 at 9:24

1 Answer 1

Reset to default
4

Context is key

Should an API return all information about an object and its foreign keys?

The first question you should ask is: where does it end?

  • If you fetch information about your street, should it contain the information pertaining to your city?
  • If you include infomation on your city, should you include information pertaining to your state?
  • If you include infomation on your state, should you include information pertaining to your country?
  • ...

You have to draw a line somewhere, and you draw that line subjectively and contextually. There is no universal answer to your question.

For example, there may be cases where you know for a fact that the consumer is interested in the related data. At that point, it makes a lot of sense to include that data since it saves you the overhead cost of sending/handling a second web request.

But what if the consumer only sometimes is interested in that related data?

  • Every time you send it and the consumer doesn't need it, that's a waste of bandwidth (and presumably DB performance).
  • Every time you don't send it and the consumer does need it, that's going to cost you the overhead of a second web request.

You're going to have to err one way or another. The third option is to develop both options, which takes more development and maintenance effort. Would you rather spend more development effort, spend performance handling additional web requests while keeping web requests at a minimum, or would you rather spend some extra bandwidth to avoid handling any more web requests than you have to?

The amount of times a consumer is interested in the related data influences this decision.

  • If it's 100%, you should include it.
  • If it's 0%, you should not include it.
  • For any % between 0 and 100, you're going to have to decide which is the lesser of two evils (using more bandwidth vs handling additional web requests)
  • It's possible to pick a third evil to avoid the other two, by developing both methods, but decisions like these tend to become effort drains for your developers and maintainers. Generally speaking, this is the least desirable decision.
Improve this answer
1
  • Thank you very much for this response. Its cleared up a few things for me!
    – wtreston
    Commented Mar 4, 2020 at 11:11

Not the answer you're looking for? Browse other questions tagged or ask your own question.