The REST API Design Handbook

by George Reese

The negotiating of the version of the representation is really more like representation negotiation—in other words, it is a function of the headers. Indicating versioning through query parameters also gets around my identification concerns, but I feel it’s an abuse of query parameters and it creates a risk of query parameter conflict. First, I believe the role of query parameters in a RESTful API are to constrain a search or a “directory” listing. They should not be used to convey other kinds of information. Second, when you pick the name of your version query parameter, you must be certain that no request on any resource in the system needs to look for a query parameter with that same name. I like headers specifically because: • They align well with other kinds of content negotiation and I see versions as a form of content negotiation. • Headers have a well-defined space for extending without conflicts (the x-whatever space). • They don’t abuse any HTTP concept like URI versioning abuses URIs and query parameter version abuses query parameters.