Syntax

The full syntax is below, in pseudo-EBNF (no comma concatenation), where Number is a number literal and rc_type is a Type or the name of a Resource Class.

rc_method = method_name [method_input] ['->' method_outputs] ';' ;
method_name = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE' ;
method_input = rc_type ['%'] ;
method_status = '#' Number ;
method_outputs = method_output [{',' method_output}] ;
method_output = method_status ':' rc_type | method_status | rc_type ;

In plain English, this means it consists of:

• A “name” - an HTTP verb
• Optionally, an input type, that also optionally has the Partial (Lax) Operator
• Optionally, an -> followed by a set of one or more comma-separated outputs, which are:
  • An output status, or
  • An output type, or
  • A status, a colon :, then a type

When an output is specified, it must have one or both of the status and type declared - it can’t be empty after the arrow.

If an output is not specified, it has the default behavior described in Resource Class.

GET and DELETE methods cannot have an input type.

Responses

The response declaration is the part that comes after the ->. It can have a status code and a body type, which can be a plain data type or a reference to another Resource Class. It must have at least one of those two, so it can have either or both.

There can be more than one, describing different possible response conditions. When Doc Comments is implemented, they can all be documented independently.

If there are more than one response declaration, they are separated by a ,. By convention, the “happy path” or success state should come first.

Status Codes

Status codes begin with the # prefix - they are raw integer status codes for now, but keywords may be introduced for HTTP reason phrases instead of codes in the future. Also there may be Wildcard status matches later on.