Styjun

I have a public REST API that, among all the exposed resources, exposes these:

POST my/webservice/foos/
PUT my/webservice/foos/fooId

both resources use a JSON model like the following:

 "a": "a mandatory string",
 "b": "another mandatory string"

So, every time a user creates a new Foo or updates an existing one, he will have to specify both the new a and the new b. So far, so good.

Now, suppose that a Foo has actually more than those two properties, say it has also a string "c", for the sake of the example. That string c admits null among the set of its possible values. Obviously, that c property has some other way to be set. Let's say it can be set on an existing Foo though a web interface.

Let's consider a Foo having a="string a", b="string b" and c="string c".
I call wih my REST client the PUT function above on this Foo object, and the new state of my Foo is: a="new string a", b="new string b", c="string c", and that's perfectly fine.

Now suppose that an update to the REST API is deployed, and the JSON model for Foo includes also c:

 "a": "a mandatory string",
 "b": "another mandatory string",
 "c": "a new optional string"

If, with the same client as before, I call the same PUT function with the same JSON object as before, my Foo will become: a="new string a", b="new string b", c=null, which, from the client perspective, is quite unexpected..

I totally underdstand that introducing a not-null new property would be a breaking change in the API that would require some kind of versioning. But do you think this case should be treated as a breaking change as well? Should I have a v1 version that only updates a and b, and a v2 that updates a, b and c? Is there any best practice to avoid increasing the version number for such changes? Is using PATCH a practical solution?

But do you think this case should be treated as a breaking change as well?

Not if you plan in advance.

Adding extensions to your message schema is fine, so long as you pay some attention in communicating up front that only optional elements may be added, and that the processing rules include Must Ignore:

Must Ignore Rule: Document receivers MUST ignore any XML attributes or elements in a valid XML document that they do not recognize.

and MUST Forward

Clients MUST FORWARD (unchanged) any input fields (URL or FORM) that the client does not recognize.

So for example, if the client knows about required element A and optional element B, but the server also knows about optional element C, then when the client GETs the resource, it will receive a:..., b:..., c:... -- it can change the elements that it knows about, but it must leave element C alone, and include it in the PUT that it sends back to the server.

The processing model for c tells the server what to do with a new message that doesn't include it.

I totally underdstand that introducing a not-null new property would be a breaking change in the API that would require some kind of versioning. But do you think this case should be treated as a breaking change as well?

Only if your API is RPC based. REST, which is just a generalization of the Web, is designed in a way to adapt to changes easily. Content on the Web is changing constantly without breaking clients. How does the Web achieve this?

Although I usually agree with Voice, I have a bit different take on this one actually. In a REST architecture a server or API should teach a client on how to do things. How should a client know what a server expects to receive on a certain endpoint? Swagger or similar documentation approaches are mainly useful for RPC-based APIs, but REST has HATEOAS. Here, the hypertext is used to drive application state. This means that a client will use the response received to explore new possibilities.

A traditional interaction flow used in the Web is that a client will invoke a URI it is interested in and receive a response which is rendered for the user to take further actions upon. In case of expected user input the server will return a Web form where a user can enter data the server expects. This is exactly how clients are taught by the server what they have to send to the server. The server of course will check the input upon reception to avoid string literal inputs on expected number fields and such or validate whether such a data element already exists. This way a client does not need to know in advance what data the server might expect. If you introduce a new field the client will learn that new field upon reception of the response.

A similar approach can and probably should be taken in a REST architecture. Either reuse HTML forms, use some similar approaches like halo+json or define your own media type which you should register with IANA. It might be advisable to check for already existing media-types first and see if they offer the capability you need. A client, of course, needs to be able to dynamically render the form based on the received content. This might be a non-trivial task though plenty of browsers could be taken as reference here.

While HTML forms do not support PUT, DELETE or PATCH, the concepts still can be applied to REST. I.e. upon clicking the send button the client is usually sending all of the input in a application/x-www-form-urlencoded representation to the server, unless the client specifies an other enctype, and it is up to the server to transform the data to something it will further work upon, i.e. create a new resource, start a backing process or invoke a further service. PUT is defined in a way that allows it to either:

• reconfigure the target resource to reflect the new media type


• transform the PUT representation to a format consistent with that of the resource before saving it as the new resource state


• reject the request with a 415 (Unsupported Media Type) response indicating that the target resource is limited to its current media type.

How the data of a resource is stored at the server side is usually an implementation detail not of relevance to the client. It can be stored simply as map or dictionary object containing arbitrary keys and values that describe the content or it could be mapped onto certain classes used in object oriented programming. It could furthermore just be stored as plain text in a file or as byte blob in a database. Ideally though, a server can map the resource's state to different representational media-type formats, which also makes content type negotiation more dominant and avoids typed resources.

This whole concept of a server teaching a client what it needs and the client being able to dynamically render the content based on the data received allows clients to learn new stuff on the fly and adapt to changes easily. This is actually a core feature of a REST architecture and one of the main selling points why APIs that have plenty of clients not under their control should aim for such an architecture.

Should I have a v1 version that only updates a and b, and a v2 that updates a, b and c?

You might read about Fielding's take on versioning which simply boils down to: don't (in the sense of sticking client-visible version numbers inside URIs). Basically if you follow the server teaches, client learns approach outlined above there is no real need for versioning numbers anyway, except for the API owner's own sake of versioning changes. Clients in a REST architecture will only ever receive the latest version anyway, or to be more precise the version the server is exposing to them, and be able to handle it. Only RPC-based clients that expect a certain version on the server will have problems adapting to those changes if the server does not separate also the data they received. In such a case probably a switch of the general namespace is preferable in general to avoid confusion.

Is there any best practice to avoid increasing the version number for such changes?

As outlined throughout the post, server should teach clients while the latter one should explore their opportunities on analyzing responses. This is something that involves both parties. Even if you have a server respecting all of the constraints a REST architecture imposes, a client that parses and analyzes URIs rather than using link-relation names, that expects resources to return certain types instead of negotiating about the representation format both parties understand or that is unwilling to learn from a server and instead applies out-of-band knowledge programmed into the client will break over time and thus will not be able to interact with such a server further.

Is using PATCH a practical solution?

PATCH is usually a misunderstood HTTP method. It is similar to patches used in programming where a patch contains changes to apply onto some given code to transform it to a desired output. The same should actually be done via HTTP. A client should take the current representation of the resource and calculate the changes necessary to transform the resource's state to the desired one. One aspect of patching that is usually neglected is, that patches need to be applied atomically. Either all of the changes are applied or none should be.

A media-type that leans towards traditional patching is application/json-patch+json defined in RFC 6902 which defines a set of instructions to apply onto a resource viewed as JSON object. Via JSON Pointers the respective segments to be changed within the current representation are addressed within the JSON Patch document.

A different approach to patching is defined in RFC 7396 which defines a more practical approach on how to apply changes to the original resource. This is covered by application/merge-patch+json. The difference between JSON Patch and JSON Merge Patch is, that the latter one does not define operations to apply onto the document but contains the whole updated document within the request. It therefore relies on a number of fixed rules to apply. I.e. if a new field appears in the request than an insert of that field is performed while if the value of an existing field changes it results in an update of that field. Deletions are achieved through nulling out values.

A more thorough explanation on how to patch can be found in William Durand excellent blog post Please do not patch like an idiot.

In practice PATCH should be used if you have partial updates to perform onto a resource's state as PUT is defined to replace the whole content with the one provided, after performing some validity checks of course. While PUT also contains a hint on how a partial update could achieved through overlapping resources, this technique is rather uncommon I guess. For the given scenario of adding new fields as of a version upgrade, I think that patching is not the right way you should aim for and instead attempt a server teaches, client learns approach as outline throughout this answer.