While adding a feature to the Discussion API, questions arose regarding the best way to handle optional fields, as well as handling API versioning.
For the Discussion API, we wish to add profile images for users to certain endpoints, but to add them optionally for performance reasons.
Of the options listed below, we have decided to implement option #4.
The Discussion API responses are currently flat:
{ ... "group_name": null, "author": "example-user", "created_at": "2015-04-09T17:31:56Z", ... } |
Ideally, the profile image would be added under the author (as part of a v2 breaking change), like the following:
{ ... "author": { "username": "example-user", "profile": { "image": { "raw": "http://...", "small": "http://...", }, }, }, ... } |
The current convention for expanding objects using "?expand=" doesn't seem granular enough because we don't want to include all profile information, at least at this time.
What would be the best parameter option:
A profile imagine unique query param.
The next question is around the best way to evolve our APIs and determine when and if we should make backward incompatible change.
A backward compatible compromise that moves us toward a more ideal response to avoid bumping versions.
{ ... "author": "example-user", "author_details": { "profile": { "image": { "raw": "http://...", "small": "http://...", }, }, }, ... } |
Introduce v2 of the API and make a backward incompatible change.
{ ... "author": { "username": "example-user", "profile": { "image": { "raw": "http://...", "small": "http://...", }, }, }, ... } |
This option has additional questions related to API versioning:
Keep a semi-flat structure and add profile_images to the top-level. The profile_images itself would not be flat, and would allow for an image per user, keyed by user id.
{ ... "author": "example-user", ... "profile_images": { "example-user": { ... }, "username2": { ... }, "username3": { ... }, } } |
Add a structure for user details keyed by user id.
{ ... "author": "example-user", ... "users": { "example-user": { "profile": { "image": { "raw": "http://...", "small": "http://...", }, }, }, "username2": { ... }, "username3": { ... }, } } |