0

When designing a RESTful API, providing a spec for updating an entity will force the designer to make some decisions on how the update will behave (an update mode or type). Here are some of the modes I can think of:

  1. If the update body contains null values, ignore them and only update the values with non-null values. (This is the most common behavior, and I think this is called a Delta.)
  2. If the update body contains null values, replace existing values with these null values. (Less common in my experience; I think at one place I worked they called this an Overlay... is that typical?)
  3. Update only values that are currently null, and non-null in the update body. (I'm not sure I've ever seen this form, but theoretically there might be a use for it.)

Basically, my question is, Is there generally excepted terminology used in REST (or even software design in general) for these concepts?

What are different behaviors of updating typically called? (Type, Mode, something else?)

Do these different types/modes have names typically used?

Are there types/modes that I didn't list?

  • I have edited the answerr. I agreed with Guillaume31, He has provided a more acurated term. Feel free of unchecking the answer if you consider It no longer answers your question. – Laiv Feb 14 '18 at 20:52
  • In REST, 1 is what I'd expect from a PATCH request, while 2 is a PUT. Never seen 3. – Paul Feb 14 '18 at 23:30
  • @Laiv your answer, "no, there's not such terminology" most directly answers my question; my question was about conventional terminology for different intended behaviors when updating. Some other answers provided additional useful information (and thus I up voted them as well), but you've actually answered the question. So I will leave it checked. :) – James Dunn Feb 15 '18 at 0:54
1

Is there generally excepted terminology used in REST (or even software design in general) for these concepts?

When It comes to REST, I would dare to say no, there's not such terminology.

As Guillaume31 comments, technical details makes sense when we speak about implementation details (how to do) and looking at the question this last seems more appropiated. 1

In any case, REST is agnostic tho this sort of details.

Looking at the Wikipedia description of REST we find nothing about implementations or expected behaviors, but those inerent to the architectural properties and constraints.

We would have to research in the HTTP RFC in order to find something closer to these behaviors, but we would just find the concept idempotency. Which I think, it doesn't answer the question either.

Finally, we would find that in order to describe #2, we could say PUT and #1,3 we could say PATCH. But still not a terminology in the sense you are looking for.


1: In the original answer I did say business rules since I think that the strategy for updates are conditioned by requirements of the business. However, it's missleading. So I had to agreed with guillaume31

  • thanks! I think this answers my question. You brought up the term I'm really looking for, business rules. I'm regretting though that I made this question specific to REST; I wish I had asked it more broadly about business rules when updating anything (whether it's a web request or interacting with a database). I'm thinking now about how to phrase a new question that is different enough to warrant different answers and not be considered a duplicate. At any rate, you've answered my question, so +1 and accepted. – James Dunn Feb 14 '18 at 19:49
  • Just remember that software engineering has borrowed a lot of terminology from other disciplines. Maths, Physics, Civil and Industrial engineering, Architecture ... These are a good "place" too look for similities. The community would adopt them for sure. – Laiv Feb 14 '18 at 19:53
  • They are not business rules, they are technical details in the plumbing of how a set of changes is applied to an existing resource. – guillaume31 Feb 14 '18 at 20:14
  • 1
    @guillaume31 I have edited the answer since the question has been focused from the technical (how to) point of view. You are right. But still I think that the updates strategies are tightly related to the business (what to do). – Laiv Feb 14 '18 at 20:51
3

I recommend to get familiar with JSON Patch Standard. I use it by myself a lot in my softwares and it makes very easy to handle the updates of the entities in a controlled way. The main idea is to describe every change as operation and send them within a JSON array to server in a single request.

2

PUT is a no-brainer : the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. (i.e. entirely)

For PATCH:

IMO you won't find anything about that in REST literature let alone HTTP RFCs. It's much too specific. Every server is basically free to implement PATCH as it sees fit along the lines of: The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. The set of changes is represented in a format called a "patch document" identified by a media type.

  • Thanks for the insight! I haven't worked with using PATCH before. My question is more along the lines of business rules terminology, not REST verbs, so this doesn't really answer my question, but I still learned something from your answer, so I'm giving you an upvote. :) – James Dunn Feb 14 '18 at 19:44
  • You can't answer the Q without mentioning HTTP verbs since you are to some extent constrained by them. For instance, 1. and 3. are not feasible in a PUT scenario. – guillaume31 Feb 14 '18 at 21:33
  • You're right, since I made this question rest-specific HTTP verbs ought to be mentioned since they require certain behavior. However, my question was still about terminology. I think part of the problem is I made a mistake when I made this question REST-specific, but I will let the question stand as-is. Thanks for your answer, even though it's not the one I accepted, I still find it very informative and useful. :) – James Dunn Feb 14 '18 at 23:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.