0

I've spend many hours reading about DataContact and ServiceContract versioning techniques:

Best practices for API versioning?

My take away from all of these are the following

1) REST Uri's needs to be versioned.

[http://example.com/v1/car]
[http://example.com/v2/car]

2) Each REST resource operation that involves XML needs to contain XML namespace 

<SampleItemCol xmlns="http://api.sample.com/2011/04/05">
  <Items>
    <SampleItem xmlns="http://api.sample.com/2011/04/01">
      <Test xmlns="http://schemas.datacontract.org/2004/07/WcfRestService2">String content</Test>
      <Id>2147483647</Id>
      <StringValue>String content</StringValue>
      <TestGuid>1627aea5-8e0a-4371-9022-9b504344e724</TestGuid>
    </SampleItem>
    <SampleItem xmlns="http://api.sample.com/2011/04/01">
      <Test xmlns="http://schemas.datacontract.org/2004/07/WcfRestService2">String content</Test>
      <Id>2147483647</Id>
      <StringValue>String content</StringValue>
      <TestGuid>1627aea5-8e0a-4371-9022-9b504344e724</TestGuid>
    </SampleItem>
  </Items>
</SampleItemCol>

So here are my questions:

1) Assuming there are hundreds of data contracts and many ServiceContracts, what would be the best class library structure to maintain different versions and namespaces?

2) If Uri's are versionined, do we even need to specify namespace for ServiceContracts?

3) Suppose there are 50 data contracts. All of them have namespace http://example.com/2011/04/01/. If 10 of these change and new namespace is created, http://example.com/2011/04/05/. Should the other 40 be copied to new namespace as well?

My biggest concern about REST namespaces and URI versions is the maintainability and class redundancy.

Thanks in advance for you suggestions and answers!

Community
  • 1
  • 1
Alex
  • 170
  • 1
  • 6

1 Answers1

1

I went down this route with versioned service contracts and datacontracts. It was a nightmare. The worst/best part is that if you take advantage of hypermedia you really do not need to version your API at all.

If you read shonzilla's post again you will see that he is really not advocating putting versions in the URI. He shows a way to do it by using redirects, but most of his reasoning advocates against it. My previous answer to this question is here

It is also worth reading Peter Williams post on the subject.

I use XML almost exclusively for the format of my media types and I don't use namespaces at all.

Community
  • 1
  • 1
Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • Darrel, thank you for taking time answering my questions. I have few follow up questions for you: 1) Could you point me some some examples of using hypermedia with WCF? I'm really interested in trying this approach. 2) I think that REST documentation should evolve with the changes. Could you share your opinion about documentating REST services? Thanks for your help! – Alex Apr 06 '11 at 02:27
  • @Alex Here is my take on documenting REST http://stackoverflow.com/questions/1904266/documenting-a-rest-service As for hypermedia, it is not really dependent on WCF. The key is to return links for the client to follow instead of the client constructing URLs. – Darrel Miller Apr 06 '11 at 03:02