Skip to main content

How to version model validations for an API?

Rails • Asked by TRADEO

Some thoughts on API versioning:

Why is API versioning necessary at all? It is required for when we want to make some breaking changes to an API endpoint, like stop accepting certain parameters or if we remove some part of the response, which clients, already consuming our API, expect. In that regard it is pretty straight forward how we do this:

  • we create a new folder namespace api/v2;
  • we put there the controller, containing the new version of the endpoint api/v2/controllers/locations_controller.rb;
  • we implement our controller action;
  • maybe for the response we use a different active model serializer/jBuilder template.

However, what do we do, if we want to change the validation rules for a model? Let's assume, we have a field foo, which in version 1 of the API, accepts three values a, b and c. So in the model we have a validaiton like so:

validates :foo, inclusion: { in: %w(a b c) }

Now we want to remove one of the values (a) and add a new value (d). If we just change the validaiton in the model to

validates :foo, inclusion: { in: %w(b c d) }

we'll have at least two problems I can think of:

  1. If a client of the old endpoint sends value a for parameter foo they'll get a validation error.
  2. If we update another attribute bar of an existing record through the new point, which has value a for foo (set in the past through the old endpoint), then we'll get a validation error, that foo is not included in the list (which will be quite unexpected, as we update bar and don't expect to get any errors for foo, which we don't touch at all).

If we are the owner of the API client and the client is only the Rails front-end, this is quire easy, as we can just update the client and the API at once and deploy the changes simultaneously. In that case, we don't even need API versioning. However, if we have some mobile clients, we need to force-update them, which isn't a nice user experience. In that case we need the API versioning. Nevertheless, we are still faced with the validaiton problem. One solution to this would be to use from objects and move the validations out of the models and into the form objects, and have seprate form objects for each version of the API. One drawback to this approach is that, if we need to validate the model elsewhere in the application (outside of the controllers), we need to again use the form objects. So I'd like to hear your thoughts on such problems with API versioning, where you don't just make changes to the request and response structure and content of the endpoint, but also to the underlying model. Thank you.


Login or Create An Account to join the conversation.

Subscribe to the newsletter

Join 22,346+ developers who get early access to new screencasts, articles, guides, updates, and more.

    By clicking this button, you agree to the GoRails Terms of Service and Privacy Policy.

    More of a social being? We're also on Twitter and YouTube.