CODEWITHSUNDEEP
rest
doub1ejack
doub1ejack

Reputation: 11181

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

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"
     }
}

Upvotes: 1

Views: 3491

Answers (1)

Simon
Simon

Reputation: 2433

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.

Upvotes: 3

Related Questions