Can I add new REST properties without making a breaking change?

Question

We currently have 4 content types that might be included in a delivery. In about 8-12 months we will probably have another 2-4 content types. I'm working on a public REST api now and wondering whether I can write the api in such a way that the future additions won't require a version bump?

Currently we are thinking a delivery would return a json result kind of like this:

{
    "dateDelivered": "2016-01-01",
    "clientId": "000001",
    "contentCounts" : {
         "total" : 100,
         "articles": 75,
         "slideshows": 25
         ... // other content types as we add them
    }
    "content" : {
         "articles" : "http://api.example.com/v0/deliveries/1234/content/articles",
         "slideshows" : "http://api.example.com/v0/deliveries/1234/content/slideshows",
         ... // other content types as we add them
     }
}

That defines contentCounts and content as objects with an optional property for each available content type. I suppose I could define that as an array of objects for each content type, but I don't see how that would really change anything.

Is there any reason it be a breaking change if in the future the result object looked more like this:

{
    "dateDelivered": "2016-01-01",
    "clientId": "000001",
    "contentCounts" : {
         "total" : 150,
         "articles": 75,
         "slideshows": 25,
         "events": 25,
         "videos": 25
    }
    "content" : {
         "articles" : "http://api.example.com/v0/deliveries/1234/content/articles",
         "slideshows" : "http://api.example.com/v0/deliveries/1234/content/slideshows",
         "events" : "http://api.example.com/v0/deliveries/1234/content/events",
         "videos" : "http://api.example.com/v0/deliveries/1234/content/videos"
     }
}

Nope - I wouldn't consider adding properties to an object as a breaking change. Removing/moving/renaming/changing types of properties will be breaking. — cejast, Nov 15 '16 at 22:05
But you might consider having an array of content that has the name & url — Dijkgraaf, Nov 15 '16 at 22:13

score 3 · Accepted Answer · answered Nov 15 '16 at 22:11

Breaking change is a relative notion. It is breaking the client code that does not account for those changes. In your case, if a client of your REST API has hardcoded the content types, then he will need to change his code to account for new content types.

In that sense, his code is broken because it does not handle all of it. In another sense, his code is not broken because as long as you do not remove content types, his code will continue to work for the content types it supports.

If the client code is smart enough to iterate through properties and be flexible about the changes, it is fine.

In any case, if you plan on changing the model, you should mention it. Whether it is adding, removing or renaming those content types, if the client knows it, he can write a client that will successfully use your REST API. In that case, NO, it would not be a breaking change because is has a dynamic structure (content types can vary) but in a structured way.

Great, that is basically what I was thinking. Do you know if there is a standardized way to indicate that a resource will be getting new properties in the future? Or perhaps using `/v0/resource` is enough of a hint :) — doub1ejack, Nov 16 '16 at 12:48
Try digging into `json-schema.org` or see this SO post http://stackoverflow.com/questions/28697209/json-schema-for-dynamic-properties Otherwise, a plain old text documentation is a way to go — Simon, Nov 16 '16 at 17:38

Can I add new REST properties without making a breaking change?

1 Answers1