Step 2: Understanding REST API versioning

Every route is registered for one or more versions with ezpRestVersionedRoute. A request for /api/<provider>/v2/... only matches the routes registered for version 2. This lets a provider change an answer in a new version while existing clients keep calling the old one.

// only version 1
new ezpRestVersionedRoute( new ezpMvcRailsRoute( '/topic/:helpId', 'MyController', array( 'http-get' => 'topic' ) ), 1 );
// versions 1 and 2 (a list of versions needs Exponential 6.0.15 or later)
new ezpRestVersionedRoute( new ezpMvcRailsRoute( '/item/:id', 'MyController', array( 'http-get' => 'view' ) ), array( 1, 2 ) );

The third argument of the route maps HTTP methods to controller actions: 'http-get' => 'view' calls doView(). A route can map several methods.

How ezprestapi uses versions

• v1: the reading routes, as the older ezprestapiprovider answered them; existing clients keep working.
• v2: the same reading routes, plus create (POST /content/node/create), update and remove. A write sent to v1 does not exist there and is refused.

Links in an answer stay in the version that was asked for.

Next: Step 3: extending the REST API.