FriendsOfSymfony/FOSRestBundle — pull request #632 by liuggio (2013-12-10 18:11:00+00:00)
Title: [WIP][RFC] yep another [Header API Versioning] recap, todo list, and PR

Hi
a little recap about the issues:
#12 #30, #610, #607, #136, #561, #612

### A. @lsmith77 approach showed in #561

One route definition, one path, multiple controllers.

``` yml
hello_version:
pattern: /liip/version
defaults:
_controller_map:
fallback: '1.0'
config:
'1.0': 'liip_hello.world.controller:v1Action'
'2.0': 'liip_hello.world.controller:v2Action'
_format: json
```

*pro* :
- really clean and easy to use
- partially already implemented
- works with sf 2.*

*cons*:
- not very flexible (is not possible to add additional parameters and constrains eg version2 is only for xml etc.)

*Note*: need to implement something for the naming collision

### B. @adrienbrault approach showed in #561

``` yml
hello_version_v1:
pattern: /liip/version
defaults:
_controller: 'liip_hello.world.controller:v1Action'
_format: json
condition: 'matchesVersion(request, "1.*")'

hello_version_v2:
pattern: /liip/version
defaults:
_controller: 'liip_hello.world.controller:v2Action'
_format: json
condition: 'matchesVersion(request, "2.*")'
```

*pro* :

- flexible will use the Exp.Lang.
- each version has a separated route (so it may possible to add additional parameters and constrains eg version2 is only for xml etc.)

*cons*:
- different route same path (is this a problem?)
- will work only in >=SF2.4
- no explicit fallback

### C. @amenophis in the #612

using annotations `@since`, `@until` is possible to filter controller.

*pro* :

- simplest approach
- partially already implemented

*cons*:

- not so clean (maybe because I don't get the goal)
- only annotations (?)

## This PR

This PR just wants to reach the goal of API version asap,
using the fastest and the way to do it, the Expression Language, has all the cons of the *B*.

Now already works with

```
users:
type: rest
prefix: /
resource: "@AcmeDemoBundle/Controller/UserController.php"
name_prefix: api_1_ # naming collision
condition: "request.headers.get('X-API-Version') matches '/1.0/i'"
```

But is better create a function and register it (as Adrien has suggested)
the goal is to have:

```
users:
type: rest
prefix: /
resource: "@AcmeDemoBundle/Controller/UserController.php"
name_prefix: api_1_ # naming collision
condition: "matchVersion(request.headers.get('X-API-Version'), '>1.0')'"
```

If you decide I could continue with:

- [ ] Tests
- [ ] Develops and register a semver function for the EL

optional:
- [ ] Find a way to register a custom function for the EL