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?
LinkedIn
Twitter
