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.