DEV Community

Paul Asjes for WorkOS

Posted on • Edited on

old

Top comments (9)

Collapse
 
ajitzero profile image
Ajit Panigrahi

On the last example, I believe a PUT call should respond with an error status for missing fields, and for partial changes we should use PATCH instead. But considering your point to be intuitive, I would say we should send an optional suggestion field in the PUT case but still cause it to error out. e.g.:

{
   // Some internal error code for tracking
  "code":  "MISSING_REQUIRED_FIELDS", // or: -1

  // can be used for showing error message in UI.
  "message": "Required fields: 'name', 'email'.",

   // can be hidden from UI but REST API users can see the help text.
  "suggestion": "Use PATCH for partial updates."
}
Enter fullscreen mode Exit fullscreen mode

Intuition should not break conventions.

Collapse
 
freddyhm profile image
Freddy Hidalgo-Monchez • Edited

Awesome share! Completely agree with the human-centric approach. As engineers I think we too often fall in the trap of developing "perfect" solutions in our heads and forget to include the target audience in those discussions.

In a way, I see API design similar to developing a new product: lean principles can help build the most useful thing. This book also highlights how important that is (not affiliated or sponsored, just a fan 😛) manning.com/books/the-design-of-we...

Collapse
 
irreverentmike profile image
Mike Bifulco

Here’s a guy who knows what’s up. This is a great one, Paul!

Collapse
 
rolfstreefkerk profile image
Rolf Streefkerk

It seems what you call human centric is following business requirements in the end.

Collapse
 
paulasjes profile image
Paul Asjes WorkOS

Can't those two have the same goals?

Collapse
 
rolfstreefkerk profile image
Rolf Streefkerk

It seems to me they're almost the same thing, except business requirements is more broadly scoped to also consider the need of the business context. I think this is maybe where I'm possibly getting confused and we're mixing definitions.

Collapse
 
certifieddev19960101 profile image
certifieddev0101

I think this is very useful for dev. Perfect!!! 🙂

Collapse
 
catsarebetter profile image
Hide Shidara

Is it a design pattern if you're considering subjective data like human need? That implies that the design pattern is open to interpretation, which is an anti-pattern in engineering

Collapse
 
mountstack profile image
mountstack

Great