Update a Resource along with Justification Message

[Rajat Gupta]

Hi

I have a Customer Resource, its schema is standardized across enterprise. I have standard GET, POST , PUT , DELETE methods defined on this resource.

When I update this resource I need to pass a reason/justification message for the update/change.

How do I achieve it ? Possible options :-
1. Change Customer resource and add a message field
2. Create a new resource "updateCustomer" (or something else) which is nothing but Customer + message >> but that would be deviating from REST paradigm
3. Any other approach ??

Thanks
Rajat

[Chris Mullins]

I don't think this is an API problem. It sounds more like a schema versioning problem. 

What's preventing you from updating the schema, and revving the API? That's the obvious solution, and the obvious solutions are often best. This is the solution that would have rich support for things like error messages, and allow you to make guarantees around the new data being present. Both of these seem like worthwhile goals. 

Taking a much more loosely coupled approach probably isn't worth the trouble. As you fast forward a few years after going down that road, you'll have a dozen random fields to update in addition to the primary API. Ick. 

For me, I would just update the schema. Hopefully you have a suitable versioning mechanism in place for both the Schema and the relevant APIs. If not, it may be time to grow scope and add that. 

Cheers,

Chris

[Rajat Gupta]

We are maintaining schema versions and adding a new version is not a big deal. The question was more from a resource design perspective. As this particular field is only used for update and maintained in Backend for audit purposes. I was finding it hard to add to the resource without exploring other possible solutions.

Thanks

[Rajat Gupta]

We are maintaining schema versions and adding a new version is not a big deal. The question was more from a resource design perspective. As this particular field is only used for update and maintained in Backend for audit purposes. I was finding it hard to add to the resource without exploring other possible solutions.

Thanks

On Friday, February 20, 2015 at 11:14:00 PM UTC-8, Chris Mullins wrote:

[Kijana Woodard]

REST does not limit you to four verbs on one noun. Further, you can POST data that isn't on the GET representation. I think some would say this is true for PUT as well, but that is more controversial.

In other words, it is fine to require the reason when modifying customer.

You could even expose the audit trail under /customers/123/audit.

Personally, I'm much more alarmed by an enterprise wide consistent schema for customer. But that is a topic for another forum. :-)

---

From: Rajat Gupta
Sent: ‎2/‎21/‎2015 2:41 AM
To: api-...@googlegroups.com
Subject: [api-craft] Re: Update a Resource along with Justification Message

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Rajat Gupta]

When you say "POST data that isn't GET representation", can you give some specific examples ? The one I could think of is validation API but that's a process and not a resource.

For the audit trail example, I dont think it would be a good idea as I will end up maintaining the "state" (or session) on server side to keep track of changes made by the client. Also what if client didnt call audit API, what should the server do ?? Rollback ??

Also, I didn't understand your concerns around enterprise consistent schema !!  I have seen a "Common Object Model" or "Shared Object Model" implemented in multiple enterprises. They are taken from "SOAP" world but should be good for REST too.

[Kijana Woodard]

"... can you give some specific examples ?"

GET /api.example.com/customers/1

{ "Name": "Jym" }

POST /api.example.com/customers/1

{ "Name": "Jim", "Reason": "Typo" }

GET /api.example.com/customers/1

{ "Name": "Jim" }

"...I didn't understand your concerns around enterprise consistent schema !!  I have seen a "Common Object Model" or "Shared Object Model" implemented in multiple enterprises."

I've seen this quite often as well. It usually ends in disaster...or stagnation...which is disaster. Any enterprise large enough to consider a "Common Object Model" should instead have many models whose shape is dictated by the Ubiquitous Language of each context. Shipping's understanding of a Customer !== Billing's understanding of a Customer. This topic is best suited to other forums as it is OT here.

[mca]

when you POST a message w/ 12 inputs, what makes you think that all the fields are written to a single place|table|file? if not one place, how many? are all fields written to disk? and what about the fields you don't send in the POST (monotonic IDs, dateCreated, sessionID, etc.).

it helps to start thinking of HTTP as a message-passing system instead of an object/structure-passing system. 

cheers.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund