services

This is a very rough description and is subject to change

A service is a collection of resources. Every resource has a root resource field such as /users and a number of operations on it: read, update, create etc. All this information is described by the schema file.

Operation declaration consists of

• operation kind: read, update, create, delete or custom
• operation name. Optional for CRUD, mandatory for custom. There can be at most one unnamed operation of every kind. Operation names are mostly used for routing, they allow to explicitly specify which operation to invoke
• optional operation path. Path is a non-branching projection which allows to attach an operation to some field nested deeply under the resource field
• operation projections, of different type and number, depending on the operation kind.

Projections that tells the system:

• what exactly an operation can build
• what kind of input data can it receive
• which parameters does it take
• any kind of custom attributes such as permission rules, to be handled by operation implementation

Framework guarantees that

• a proper operation will be invoked, basing on operation kind, name, path and request projection
• request path matches operation path
• request projection doesn't ask for anything an operation can't build
• any input data operation implementation receives fits into operation projection
• all the required parameters are provided and their types are correct
• operation output is covered by the request projection
• if operation builds more data than asked for, then any unnecessary data will be trimmed away

Resource declaration example:

namespace ws.epigraph.tests

import ws.epigraph.tests.Person
import ws.epigraph.tests.PersonId
import ws.epigraph.tests.PersonRecord
import ws.epigraph.tests.User

resource users: map[PersonId, Person] { // resource type is a map

  read {                 // unnamed (default) read operation
    outputProjection []( // operation output is a map, where every entry is a Person
      :(
        id,              // with `id` representation supported
        `record`(        // and `record` supported too
          id,               // `record` can contain `id` field
          firstName,        // and some more felds
          lastName,
          bestFriend:(      // and a bestFriend in two representations
            id,
            `record`( id, firstName, lastName, bestFriend:id, worstEnemy )
          )
        )
      )
    )
  }
}