{"id":21962214,"url":"https://github.com/orangecoding/versioning","last_synced_at":"2025-07-04T08:36:29.040Z","repository":{"id":72199849,"uuid":"414532725","full_name":"orangecoding/versioning","owner":"orangecoding","description":"Example of how to do proper versioning of RESTful apis","archived":false,"fork":false,"pushed_at":"2021-10-07T09:23:37.000Z","size":136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T20:45:17.750Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/orangecoding.png","metadata":{"files":{"readme":"README.md","changelog":"changelogGenerator.js","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-07T09:09:32.000Z","updated_at":"2021-10-07T09:23:40.000Z","dependencies_parsed_at":"2023-05-31T08:00:45.890Z","dependency_job_id":null,"html_url":"https://github.com/orangecoding/versioning","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/orangecoding/versioning","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Fversioning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Fversioning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Fversioning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Fversioning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orangecoding","download_url":"https://codeload.github.com/orangecoding/versioning/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orangecoding%2Fversioning/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263477708,"owners_count":23472843,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-29T10:35:33.827Z","updated_at":"2025-07-04T08:36:28.964Z","avatar_url":"https://github.com/orangecoding.png","language":"JavaScript","readme":"## Api Versioning\n\nJust recently I came across the question of how to do proper API versioning for RESTful apis.  \nThere are many ways to do this. In the early days, it was common to version api endpoints with a prefix.\n```\nv1/some/api\n```\n\nHowever, this turned out to be a bad idea for various reasons. If you serve your api by providing a set of clients,\nyou have to release a new client on every change. If you don't, you have to somehow communicate to the customer to use the next\nversion of the api to be able to use new features.\n\nThe result is a lot of different endpoints in your code (that mostly do the same) as well as the necessity to either always release new clients or make sure, customers are using the latest v(x).\n\n### A potential solution\n\nThere are various ways how to solve this. One of them is to use what I call the \"transformer pattern\". Basically every api endpoint has its own transformer. All calls first run through a transformer before the result is sent to the customer. (You would have different transformer for incoming data (POST/PUT) or outgoing data (responses), this example only takes care of transforming responses to avoid any unnecessary complexity)\n\nThe api consumer either sends the version they are using in the header of the request, or it is being set on the dashboard. Based on this version and the transformer, we know how to transform the response. This pattern not only works for response data, but also for request data.\n\nSee the following picture:\n\n\u003cimg src=\"https://github.com/orangecoding/versioning/blob/main/doc/doc.jpeg\" width=\"50%\"\u003e\n\nThe example code in this repository explains the pattern by providing 2 api endpoints. Based on the given api version, the necessary transformations are being applied.\n\nHopefully start to see the goodness of this pattern by now. You don't have to add new endpoints when changing the way how they consume or provide data. Another advantage is that you have everything you need already to put together an api changelog, as changes have been described per transformer.\n\n### Usage\nStart the example server by running   \n```bash\nyarn run start\n```\n\nA server on portal 5000 will be spawned. Available api calls are:   \n```\nhttp://localhost:5000/api/person\nhttp://localhost:5000/api/cars\n```\n\nIf you want to change the api version that is being used, change it in `index.js`. (Obviously as described above, this version normally is being sent by the api consumer or stored at the consumer data somewhere)\n\nIf you want to generate a changelog, you can do so by running\n```\nyarn run changelog\n```\n\n\n## DISCLAIMER\nThis repository is solely for educational purposes to explain the pattern, it is by FAR not meant to be used for any production purpose. If you want to use this in production, you have to not only take GET requests into account, but also PUT, POST etc.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forangecoding%2Fversioning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forangecoding%2Fversioning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forangecoding%2Fversioning/lists"}