7

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?

MHOOS
  • 5,146
  • 11
  • 39
  • 74
  • test.myapi.mysite.com sounds like a good approach however in regards to using "request header to differentiate between live and test" defeats the whole purpose of using "url versioning visual superiority" in terms of visual inspection in comparison to header versioning. client demands something as easy as a url to put in his live/test config files without manipulating the header. – MHOOS Dec 29 '16 at 13:09
  • Have you considered using feature toggles. You could have live data available to the majority of users but then switch to test data for developers. You could also give the developers the ability to turn on and off test data for themselves without changing urls at all. – Woot Jan 03 '17 at 19:59

5 Answers5

3

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.

Community
  • 1
  • 1
YuriW
  • 869
  • 1
  • 11
  • 22
1

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.

venerik
  • 5,766
  • 2
  • 33
  • 43
1

Most of the live projects different server for different environments. Instead of using different version of API endpoints, You should use different servers for different environment like this :

For Prod/live : https://myapi.mysite.com/v1/customer/2

For Test : https://myapi.mysitetest.com/v1/customer/2

For Dev : https://myapi.mysitedev.com/v1/customer/2

You need to configure environment specific properties for different backend endpoints you are hitting. Like : test.properties/dev.properties/live.properties

Siddharth Kumar
  • 86
  • 2
  • 13
0

With my experience in API developing i found that there are 2 way of making server (test/developer)/live I will show an example with your link type https://{fqdn}/{apiVersion}/{apiResourceName}/{resourcePath}?{parameters}

In your case you can use or settings based and Link based testing type

What is settings based?

Settings based is that your server for example https://rest.mysite.com/v1/customer/2 will acting as test if you or your customer will set in he's settings server status to test and if as live - status to live. This method is good in some cases but in order to test and to have live in same time,- this type not recommended.

What is link|URL|URI based?

This method have 2 types of identifying request is test or live

  1. One way is to set test as a parameter https://api.mysite.com/test/v1/customer/2 and without test it goes to live
  2. Second way is to set api to testApi or apiTest for example https://testapi.mysite.com/v1/customer/2 or https://apitest.mysite.com/v1/customer/2 . This way customer have both test and live and he can do testing and having live project too.

And don`t forget for security always check customer and verify before giving live api access.

Davit Gabrielyan
  • 196
  • 2
  • 7
0

As an option you may use custom defined header. If request contains custom header -> redirect request to test version of API.

Set
  • 47,577
  • 22
  • 132
  • 150