API Versioning: providing different data formats for a resource

Well, in your example only the controllers and resources seem to change per version number. The general database structure seems to stay the same and extra data is added.

In that case, I would go for separate directories per version in your resources and maybe even in your controllers' directory structure. This way, you can keep all the previous available code and build out a new version with some different data or different keys.

You can find a good example here: https://medium.com/@juampi92/api-versioning-using-laravels-resources-b1687a6d2c22

Well, If a book has a different image for some versions, there should be a "version_id" column in the "images" table in the database. and accordingly also a "versions" table.

So the database is also concerned.

and also to know which books are associated with which versions, there should be a "version_d" somewhere in the database for books.

Does it make sense to have your data connected to the versioning of your API?

Why should the data change depend on a new API version? The book name and author stay the same, right? For the images, you can solve this with a polymorphic relationship on images and include an extra field for the version number if needed. If no version number is provided it's available for all versions.

@kiasaty APIs shouldn’t change that frequently. Once you’ve published an API, that’s a contract that clients have to adhere to.

If you find you’re changing the “shape” of your API requests and responses frequently, then that’s probably an indication you need to sit and properly think through your application’s resources, their fields, relationships, and so on before committing to something that third-parties are going to consume. Otherwise you’re going to find you’re constantly publishing new API versions, which in turn forces consumers to update their code, which is inefficient and time-consuming. You’re going to be spending more time supporting integrations than you are building features that provide business value.

@bobbybouwmann Your right about the images. this is what I did exactly.

but what about the books? assume we have a total of 10 books. mobile app v1 should only receive the first 5 books, and the mobile app v2 should receive all the 10 books. ("book" are just an example)

how should I handle this?

@martinbean This is a different scenario. maybe I have not explained it right.

the API is not a public API. it's only used by our mobile app.

but the problem is, the mobile app has different versions.

assume it is an "exam app". there is a database table named "exams"

the app v1 has 5 exams, which users can choose.

in the app v2, the team decides to add 5 more exams. but these new exams shouldn't be shown on app v1.

how should this be handled? How to provide different sets of data to different versions?

@kiasaty Your basically not asking about versioning here, but about authorization. What app is allowed to see what book or in your case exam?

You should probably have a database table or config file that configures what app should return what data. So you should always send the app information along to the backend so you can divide what data you're going to fetch. In general, a pivot table is a good solution for this.

@bobbybouwmann This is what I did at the beginning. but things get more complicated.

I created an "app_versions" table in DB and created a pivot table with "book_id" and "version_id" columns.

but handling and inserting app versions in the API is not a good idea. because there are two kinds of apps: android and iOS. and these two have their own major and minor versions. and minor versions are not the same. so an "OS" column is needed in the versions table. and we should assign every single book to all these major and minor versions for both OSs.

• andorid versions: 1.0.0 1.1.0 1.3.0 1.3.1 2.0.0

• iOS versions: 1.0.0 1.0.1 1.2.0 1.3.0 2.0.0

minor versions in iOS and Android apps are different. every minor version in each OS should be inserted in the "app_versions" table in the API, and then all the books in the pivot table should be repeated.

See? this solution leads to complications as the app grows.

So a better solution is that we version the data in API, instead of keeping track of app versions in the API. and let the app decide which dataVersion to choose through API versioning.

now I want to know is this a reasonable solution? is there a standard or best practice to handle this scenario?