version- and documentationsystem for Helppages

Topics: Web Api
Apr 26, 2011 at 1:42 PM

Hi,

are there any plans (or best practices how) to implement a documentation- and versioningsystem for REST based API? I need a system that generate automaticly helppages .. at the moment I'am using custom attributes to build that kind of pages. But I've there will be a "standard" in the web-api project I would like to use that in future...

Another topic is the versioning of an REST API .. are there any best practices?

thanks & cheers,
Daniel

 

Apr 27, 2011 at 2:12 PM

There are plans to automatically produce help pages.  However, I'm not sure what status they currently are in.

Regarding REST API versioning, here are my three rules:

1) You don't need it.

2) If you really do need it then find a way to version your media types.

3) If it is too late, and you already have tightly coupled clients, then your last resort is to put a version number in the URL and start again.

Check out Stackoverflow for lots more discussion on versioning of REST apis.  Here is my opinion http://stackoverflow.com/questions/972226/how-to-version-rest-uris/975394#975394

Apr 28, 2011 at 8:38 AM

Hi,

and thank you for the answer. For documentation I will use my one system (a bit like autodocs) and hope that there will be a best practice / standard in future.

Your point of versioning is very interessting and makes sense .... the idea to use mediatype is great and flexible I will try to integrat that into our existing system.

Cheers,
Daniel

Apr 28, 2011 at 4:39 PM
DarrelMiller wrote:

There are plans to automatically produce help pages.  However, I'm not sure what status they currently are in.

Regarding REST API versioning, here are my three rules:

1) You don't need it.

2) If you really do need it then find a way to version your media types.

3) If it is too late, and you already have tightly coupled clients, then your last resort is to put a version number in the URL and start again.

Check out Stackoverflow for lots more discussion on versioning of REST apis.  Here is my opinion http://stackoverflow.com/questions/972226/how-to-version-rest-uris/975394#975394


I follwed Darrel's link and ultimately read this one:

http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

Very clear, concise explanation that details what Darrel said in his link.  Worth the read, imo.