Thoughts on partial responses & reusing objects?

[#1]

Hello everyone,

This question is around API design. We are building an API with about 10 endpoints. Some of those endpoints return datasets that are very very similar. Imagine, for example, that they each "kind of" return a Client object and a Business object. Both the Client object and the Business object contain about 20 fields. The challenge, however, is that each endpoint returns slight variations of the client & business objects. Each endpoint might return only 15 or 16 of the 20 fields of the objects, but not the full objects.

This is creating an interesting debate internally. In our API documentation, when describing the responses of these endpoints, should we say that they return the Client and Business objects? or by definition, because they dont return the full objects, should we say that they are NOT the same objects?

I want to avoid developer confusion and avoid a scenario where the developer thinks "wait, you say you return the client object, but I'm only getting down some of the fields?"

While looking online, it looks like returning partial objects is a common trend in popular APIs... doesn't necessarily mean it is a best practice though. Any thoughts?

[alan]

My thoughts on this is that you should focus on normalizing objects based who is using the APIs. For example, if you have multiple end points used by a mobile app, it is likely that there is one developer using those endpoints, so having common objects across those endpoints makes sense. But if you 2 endpoints used by two totally different audiences, normalizing the objects across both doesn't gain you anything. Infact, requires across those two users may change over time to the point that the objects look totally different. Refactoring early in this scenarios is actually at your disadvantage.

[#3]

There are different approaches to this problem depending on whether you are following a REST model or an RPC model. Words like "object' and 'endpoint' belong to the RPC model, and Alan has already given an opinion on how to solve your problem using that approach. Here is a way to think about this if you are following a REST model instead. I would first establish a URL for each 'Client' and each 'Business'. A GET on those URLs would return all the fields. Here is an example:

/clients/123456
/businesses/98765

These are the URLs of a client and a business respectively—these are your 'base resosurces'. I would then establish additional URLs for 'queries' over those resources. In this case, the queries you are interested in are 'projection' queries.

/clients/123456?fields=firstname,lastname,nickname,street,city,zip
/businesses/98765?fields=name,logo,slogan

These URLs do not identify a client or a business, they identify [the results of] queries. Of course, these particular queries are based on the state of an underlying client or business. The URL of the query does not have to be an extension of the URL of the base resource; it could look like this:

/clients?firstname=Martin&lastname=Nally&fields=firstname,lastname,nickname

In effect you are inventing your own limited query language, and the syntax is up to you. This is one of the weaknesses of the current HTTP standards from the point of view of API design—the standards specify very completely and precisely how you express CRUD, but they don't give much guidance on how you should express query, and query turns out to be important.