Route Scope#

Let's start by defining what we call a route scope.

It is a unique combination of 2 elements :

The route main entity
An operation, for example any of the C|R|U|D operations

Each route scope will have unique responses schema generated from the mapping, itself made from the list of exposed properties on that scope.

Examples#

These are the routes generated from the Quick start example :

Verb	Path	Entity	Operation	Route scope
POST	/users	User	create	user.create
POST	/users/mapping	User	create	user.create.mapping
PUT	/users/:id(\d+)	User	update	user.update
PUT	/users/:id(\d+)/mapping	User	update	user.update.mapping
GET	/users/:id(\d+)	User	get	user.get
GET	/users/:id(\d+)/mapping	User	get	user.get.mapping
GET	/users	User	list	user.list
GET	/users/mapping	User	list	user.list.mapping
DELETE	/users/:id(\d+)	User	delete	user.delete
POST	/users/:UserId(\d+)/articles	Article	create	article.create
GET	/users/:UserId(\d+)/articles	Article	list	article.list
DELETE	/users/:UserId(\d+)/articles/:id(\d+)	Article	delete	article.delete

The route main entity for subresources routes is its relation entity, here it is Article and not User.

Subresources#

This also means that subresources share the same route scope as their property entity router. For example, if you had an EntityRouter set up on the Article entity with ["create", "update", "list"] operations, you would have those routes generated :

Verb	Path	Entity	Operation	Route scope
POST	/articles	Article	create	article.create
POST	/articles/mapping	Article	create	article.create.mapping
PUT	/articles/:id(\d+)	Article	update	article.update
PUT	/articles/:id(\d+)/mapping	Article	update	article.update.mapping
GET	/articles	Article	list	article.list
GET	/articles/mapping	Article	list	article.list.mapping

So, if you need to retrieve a subresource route mapping, it's actually just the subresource entity mapping for the same operation you're looking for !

Exposing properties#

With the @Groups decorator you can expose any property (or method), from any entity in the route scope of your choice.

What that means is that you can for example have a different mapping for the User creation route and the User update route. More on that later.

Of course this also means that you can have differents constraints for each route scope. TODO Validator docref

Inferred Mapping#

The mapping is a description of every properties exposed through the @Groups decorator for a specific route scope.

A route mapping endpoint is auto-generated for every basic operations and accessible by adding "/mapping" to the path of the route, the same HTTP verb as the operation it describes is used.

This mapping route will give you the response schema expected on the actual route it describes.

There is a pretty query parameter (?pretty=true) available to make it less verbose, it makes mapping look kind of like a GraphQL request body, as you can see below.

#json
1{
2    "context": {
3        "operation": "details.mapping",
4        "entity": "user"
5    },
6    "routeMapping": {
7        "selectProps": ["name", "id"],
8        "relationProps": ["articles"],
9        "exposedProps": ["name", "id", "articles"],
10        "mapping": {
11            "articles": {
12                "selectProps": ["id"],
13                "relationProps": [],
14                "exposedProps": ["id"],
15                "mapping": {}
16            }
17        }
18    }
19}

#json
1{
2    "context": {
3        "operation": "details.mapping",
4        "entity": "user"
5    },
6    "routeMapping": {
7        "name": "String",
8        "id": "Number",
9        "articles": "@id[]"
10    }
11}

Scoped Validation#

TODO

Operations

Introduction