Test version of web API url

Question

For our Web api project we use the following url versioning system:

https://{fqdn}/{apiVersion}/{apiResourceName}/{resourcePath}?{parameters}

for instance we can have something like the following:

https://myapi.mysite.com/v1/customer/2

Now considering above, let say you want to release two versions (live,test) to the customer. One live version (working with live data) and the other one is the test (working with test data for customer development test).

For live one I could easily use the one I mentioned : https://myapi.mysite.com/v1/customer/2 .

How do you name the test version of the above api? what is the test version of a api url version v1? Can specify the test api url?

Also what are best practices for fully qualified domain name of the API {fqdn} when using url versioning?

Answer 1

There are really several ways to do this.

One way, for instance, is to simply use attribute routing to give it a different path. Create a separate method, give it a path of /vtest/customer/2 for example and if users access this /vtest/ version (or v2 or 3 or whatever) then return the test data/new version. See an example in this question

Another way is to host your "test data" API in a different application in your server and have your web.config point to test versions of your database/source data. Using IIS, you'd configure two different applications (one for test, other for live) and the base URL would differ e.g.: https://myapi.mysite.com/appname1/v1/customer/2 vs https://myapi.mysite.com/appname2/v1/customer/2 and your appname could be something like live vs test. Have a look at this simple example

You could also just host them in different servers altogether, which would result in your {fqdn} changing between test and live versions (e.g. server.com/v1/customer/2 vs testserver.com/v1/customer/2) - this is what I do at my current job, and I find it very effective as it isolates live/test data (and API versions) avoiding confusion between them.

I also found this blog post detailing how to do this with namespaces

In other words there isn't just one best/correct way to do what you want, it all boils down to how you (or your company/boss/team) wants to structure and control test vs live data in your APIs. Take a look at these options to see which one is best in your case, hope I was able to help.

Answer 2

I think the title of your question is misleading. The problem you are trying to solve is not versioning (because your client is connecting to the same version of your application: v1). It is about having multiple environments: one for live data and one (or more) for test data.

At my company we solve this issue through the host name. At https://live.mysite.com/api/v1 we host v1 of the API connected to live data. At https://nodex.mysite.com/api/v1 we host v1 of the API connected to test data. Our clients can request new nodes as necessary (e.g. client1-devnode.mysite.com/api/v1 to develop against, and client1-testnode.mysite.com/api/v1 to test against. Each node get it's own set of test data.