## Routes

A route is the rule which redirects the incoming request to an action. If a 
request arrives the first route which matches is used. In order to be able to
evolve an API it is possible to add multiple versions for the same route. For 
each version it is possible to specify the allowed request methods. Each method
describes the request and response schema and the action which is executed upon 
request. If a request method is public it is possible to request the API 
endpoint without an access token.

### Path

The path can contain variable path fragments. It is possible to access these 
variable path fragments inside an action. The following list describes the 
syntax.

* `/news`
  No variable path fragment only the request to `/news` matches this route

* `/news/:news_id`
  Simple variable path fragment. This route matches to any value except a slash.
  I.e. `/news/foo` or `/news/12` matches this route

* `/news/$year<[0-9]+>`
  Variable path fragment with a regular expression. I.e. only `/news/2015` 
  matches this route

* `/file/*path`
  Variable path fragment which matches all values. I.e. `/file/foo/bar` or 
  `/file/12` matches this route

### Status

The status affects the behaviour of the API endpoint. The following list 
describes each status

* `Development`
  Used as first status to develop a new API endpoint. It adds a "Warning" header 
  to each response that the API is in development mode.

* `Production`
  Used if the API is ready for production use. If the API transitions from 
  development to production all databases settings are copied into the route. 
  That means changing a schema or action will not change the API endpoint.

* `Deprecated`
  Used if you want to deprecate a specific version of the API. Adds a "Warning" 
  header to each response that the API is deprecated.

* `Closed`
  Used if you dont want to support a specific version anymore. Returns an error 
  message with a `410 Gone` status code

### Action

The action contains the business logic of your API endpoint. It i.e. selects
or inserts entries from a database or pushes a new entry to a message queue.