Hypothetical Question for REST API Design Discussion:
Let’s say you’re building a credit reporting API that can return complete credit report profiles for an individual. The credit profile model is rather large and contains all the details for the customer. For example, personal details, addresses, aliases, risk models (credit score), tradelines (every bank account), etc…
I would probably make the API route look something like this:
The params would be the required information (name, ssn, address, etc), and the response object would contain a mementified
Now, what if the API consumer only cares about a subset of the data, like they only want the credit score/risk model instead of the whole massive
Idea 1: New Nested Endpoint?
Would you create a new REST endpoint like this?
Idea 2: Parameters to Control Data Returned
Or would you use the original
(GET) /api/v1/creditProfiles/ endpoint but add a special boolean parameter like
riskModelOnly=(true/false), which would return just the subset of data instead of the whole model? Similar to how we allow pagination or filter params to be passed in GET requests? I’ve seen a few .NET APIs work this way where you can customize what fields/data you want the endpoint to return.
Idea 3: Cruddy by Design
I’ve watched the “Cruddy by Design” video by Adam Wathan, which makes me think Adam would recommend creating a brand-new handler at the root of the API like this:
My takeaway from Adam’s video is that he’s not a fan of building folder hierarchies and likes to stick with HTTP verbs as much as possible. In other words, if the action doesn’t match a verb, then create a new handler.
The “Cruddy by Design” approach smells off to me, though. I like the idea of handler names establishing a “domain” where users can easily predict what type of behavior, data, or actions are available by following a logical folder structure. For example, I know that
/api/v1/creditProfiles will contain one or more endpoints (or nested endpoints) all related to the “creditProfiles” domain.
What do you think? How would you solve this type of conundrum, and why?