@toa.io/extensions.exposition 0.9.0-canary.2 → 0.20.0-alpha.0

package/documentation/protocol.md

@@ -0,0 +1,15 @@
+# Protocol Support
+
+## Media types
+
+The following media types are supported for both requests and responses:
+
+- `application/json`
+- `application/yaml` using [js-yaml](https://github.com/nodeca/js-yaml)
+- `application/msgpack` using [msgpackr](https://github.com/kriszyp/msgpackr)
+- `text/plain`
+
+The response format is determined by content negotiation
+using [negotiator](https://github.com/jshttp/negotiator).
+
+> Errors are always sent as `text/plain`. See [debug mode](../readme.md#context-annotation).

package/documentation/query.md

@@ -0,0 +1,226 @@
+# Query mapping
+
+## TL;DR
+
+```yaml
+id?: string
+criteria?: string
+sort?: string
+omit?: [integer]
+limit?: [integer]
+selectors?: string[]
+projection?: [string]
+```
+
+```yaml
+# manifest.toa.yaml
+
+name: pots
+namespace: tea
+
+exposition:
+  /hot:
+    GET:
+      endpoint: enumerate
+      query:
+        criteria: state==hot
+    /top10:
+      GET:
+        endpoint: enumerate
+        query:
+          criteria: state==hot
+          sort: rank:desc
+          limit: 10
+  /latest:
+    GET:
+      endpoint: observe
+      query:
+        sort: timestamp:desc
+        limit: 1
+```
+
+Undefined `query` denies any query arguments in requests.
+
+`POST` method mapping cannot have `query` declaration.
+
+## Criteria
+
+Search critaria in [RSQL](https://github.com/jirutka/rsql-parser) format.
+
+The `criteria` property is considered as *open* when it ends with a `;`, allowing the combination of
+request query criteria using `and` logic.
+Otherwise, criteria property is *closed*, that is, doesn't allow `criteria` in a request query.
+
+```yaml
+# manifest.toa.yaml
+
+name: dummy
+
+exposition:
+  /:
+    GET:
+      endpoint: observe
+      query:
+        criteria: state==hot; # open criteria
+```
+
+```http
+GET /dummies/?criteria=rank==5
+```
+
+The request example above will result in an operation call with the following Request:
+
+```yaml
+query:
+  criteria: state==hot;rank=5
+```
+
+### Path variables
+
+Path variables are prepended to the `criteria` request query parameter using logial AND,
+except for the [`POST` method](#post-method).
+
+Given the following declaration:
+
+```yaml
+# manifest.toa.yaml
+
+name: dummies
+
+exposition:
+  /:type:
+    GET:
+      endpoint: observe
+      query:
+        criteria: state==hot; # open criteria
+```
+
+and the following request:
+
+```http request
+GET /dummies/cool/?criteria=rank==5
+```
+
+Operation call will have the following query criteria:
+
+```yaml
+criteria: state==hot;type==cool;rank=5
+```
+
+### POST method
+
+`POST` method semantically used to create a new entity instance, that is, calling a Transition
+without Query.
+Thus, path variables are added to the request input.
+
+Given the following declaration:
+
+```yaml
+# manifest.toa.yaml
+
+name: dummies
+
+exposition:
+  /:type:
+    POST: transit
+```
+
+and the following request:
+
+```http request
+POST /dummies/cool/
+content-type: application/yaml
+
+input:
+  rank: 5
+```
+
+Operation call will have the following input:
+
+```yaml
+type: cool
+rank: 5
+```
+
+> In case of conflict, path variables override input properties.
+
+## Omit, limit
+
+`omit` and `limit` properties can declare their default values and allowed boundaries:
+
+```yaml
+limit:
+  value: 10
+  range: [1, 100]
+```
+
+If no default value is provided, then the lower boundary of the range is used.
+
+Default values for `omit` and `limit` are:
+
+```yaml
+omit:
+  value: 0
+  range: [0, 1000]
+limit:
+  value: 10
+  range: [1, 1000]
+```
+
+Constant values can be declared using the shortcut:
+
+```yaml
+limit: 10
+```
+
+## Sort
+
+The `sort` query property defines the result order of Observations within an `objects` scope
+(enumeration).
+It comprises an ordered set of sorting statements delimited by semicolons.
+Each statement consists of an entity property name with an optional sorting direction suffix:
+`:asc`for ascending or `:desc` for descending.
+
+```yaml
+sort: rank # ascending by default
+```
+
+```yaml
+sort: rank:asc
+```
+
+```yaml
+sort: rank:desc;timestamp:asc
+```
+
+If `sort` value ends with a semicolon `;` then the sorting is considered *open*
+and can be extended using request query `sort` argument.
+
+```yaml
+sort: rank:desc; # open sort
+```
+
+Having the above `sort` declaration, the following request will result in an operation call
+with `rank:desc;timestamp:asc` sort:
+
+```http
+GET /dummies/?sort=timestamp:asc
+```
+
+## Selectors
+
+The `selectors` query property contains a list of Entity properties allowed for a client to use in
+the `criteria` and `sort` query parameters.
+If no value is provided, then no selectors are allowed.
+
+```yaml
+selectors: [rank, timestamp]
+```
+
+## Projection
+
+A list of Entity properties to be included in the Observation result.
+
+```yaml
+projection: [id, title, timestamp]
+```

package/documentation/tree.md

@@ -0,0 +1,169 @@
+# Resource Tree Declaration
+
+The foundation of a Resource Tree Declaration (RTD) is an RTD node.
+An RTD node is an object that consists of _Routes_, _Methods_ and _Directives_.
+
+## Routes
+
+A Route is a key starting with `/` and it has a value as a nested RTD node.
+
+```yaml
+/:
+  /users:
+    /:user-id: ...
+  /posts:
+    /:post-id: ...
+```
+
+Route declarations can also be flat, meaning that the RTD can have adjacent branches.
+The following will represent the same resources as the above:
+
+```yaml
+/users/:user-id: ...
+/posts/:post-id: ...
+```
+
+> Refer to the [Directives](#directives) section for an explanation of the differences between
+> nested and adjacent RTD branches.
+
+An RTD node that does not contain any Routes is called an _RTD leaf_.
+
+> Route declarations must not have a trailing slash.
+
+### Route variables
+
+Route segments prefixed with a colon (`:`) are Route variables.
+
+> A segment may include a reference to a single variable.
+> For instance, in the route `/messages/:sender-:recipient`,
+> a single variable is declared with the name `sender-:recipient`.
+
+Refer to [Query mapping](query.md) for the details.
+
+### Route conflicts
+
+Routes with specific, non-variable segments are given precedence in routing decisions.
+
+Consider the following route declarations:
+
+```yaml
+/users/:id: ...
+/users/hot: ...
+```
+
+Request made to `/users/hot/`, will be routed to the second `/users/hot` Route,
+as it provides a more specific match compared to the generic `/users/:id` route.
+
+The priority of Routes with the same specificity is determined by the order of declaration.
+
+## Methods
+
+Methods are mappings of the HTTP methods to the corresponding operations.
+
+A Method is a key named after the corresponding HTTP method, with a value following the schema
+below:
+
+```yaml
+endpoint: string
+query?: Query
+```
+
+> Refer to [Query mapping](query.md) for the details.
+
+Methods can be present in any RTD node.
+However, it is required that an RTD leaf must have at least one Method.
+
+If a Method only has an `operation` key, it can be declared directly as the value of the `operation`
+key.
+
+```yaml
+/teapots:
+  GET:
+    endpoint: select
+  /hot:
+    GET:
+      endpoint: select
+      query:
+        criteria: state==hot
+/posts:
+  GET: select
+  POST: transit
+  /:post-id:
+    GET: observe
+    PUT: transit
+```
+
+HTTP methods can only be mapped to operations of the corresponding types.
+
+| HTTP method | Operation type                                |
+|-------------|-----------------------------------------------|
+| `POST`      | **Transition** (without Query)<br/>**Effect** |
+| `PUT`       | **Transition** (with Query)<br/>**Effect**    |
+| `GET`       | **Observation**<br/>**Computation**           |
+| `PATCH`     | **Assignment**<br/>**Effect**                 |
+
+As method mapping is unambiguous for Observation, Assignent, and Computation, a consice syntax is
+available:
+
+```yaml
+/items: compute
+/items/:id: [observe, assign]
+```
+
+### Intermediate Nodes
+
+An RTD Node that has a Route with a key `/` is an _intermediate_ Node.
+Intermediate Nodes must not have Methods as they are unreachable.
+
+```yaml
+/posts: # Node is intermediate
+  GET: select # INVALID: Method is unreachable
+  /:
+    PUT: transit
+```
+
+## Directives
+
+RTD Directives are declared using RTD node or Method keys following the `{provider}:{directive}` pattern and can be used
+to add or modify the behavior of request processing. Directive declarations are applied to the RTD node where they are
+declared and to all nested nodes.
+
+```yaml
+/posts/:user-id:
+  authorization:id: user-id
+  /:post-id:
+    authorization:role: editor
+```
+
+In the above example, the Route `/posts/:user-id/:post-id/` has both `authorization:id`
+and `authorization:role` directives applied.
+
+When it is necessary to avoid directive nesting, a Route can be declared adjacent.
+
+```yaml
+/posts:
+  /:user-id:
+    id: user-id
+  /:user-id/:post-id:
+    role: editor
+```
+
+In this example, the Route `/posts/:user-id/:post-id/` has only the `authorization:role` directive
+applied.
+
+> Directives can be declared without the `{provider}:` prefix unless there are multiple directives
+> with the same name
+> across different providers.
+
+Another way to avoid nesting is to declare an _isolated_ Node as follows:
+
+```yaml
+/posts:
+  /:user-id:
+    id: user-id
+    /:post-id:
+      isolated: true
+      role: editor
+```
+
+See [Access Authorization](./access.md) as an example of directive provider.