haveapi 0.29.8 → 0.29.9

data/doc/protocol.md

@@ -0,0 +1,570 @@
+# Protocol definition
+HaveAPI defines the format for the self-description and URLs where the self-description
+can be found.
+
+# Self-description
+The API is self-describing. It documents itself. Clients use the self-description
+to work with the API. The Self-description contains access URLs, HTTP methods,
+input and output parameters and their validators.
+A part of description is also an example usage and text notes.
+
+The API responds to ``OPTIONS /``, which returns description of whole
+API, containing all its versions. To get description only of selected version,
+use e.g. ``OPTIONS /v1/``.
+
+Every action also responds to HTTP method ``OPTIONS``,
+with which you can get description for selected action. To distinguish actions with
+the same URL, use parameter ``?method=HTTP_METHOD``.
+
+Thanks to this ability, API changes immediately reflects in all clients without
+changing a single line of code. A client can also be used on all APIs with compatible
+self-describing format, without any changes at all.
+
+# Protocol versioning
+Protocol version defines the form and contents of
+
+ - the envelope,
+ - API description,
+ - data transfers.
+
+Protocol version is in the form `<major>.<minor>`. `major` is incremented
+whenever a change is made to the protocol that breaks backward compatibility.
+When backward compatibility is kept and only some new features are added to the
+protocol, `major` stays and `minor` is incremented.
+
+# Envelope
+In addition to output format specified below, every API response
+is wrapped in an envelope.
+The envelope reports if action succeeded or failed, provides return value or error
+messages.
+
+      {
+          "status": true if action succeeded or false if error occured,
+          "response": return value,
+          "message": error message, if status is false,
+          "errors: {
+              "parameter1": ["list", "of", "errors"],
+              "parameter2": ["and", "so", "on"]
+          }
+      }
+
+Responses for `OPTIONS` requests also send a protocol version in the envelope:
+
+    "version": <version>
+
+## Localization
+
+Servers may localize user-facing response strings using the HTTP
+`Accept-Language` header. Localization changes only string values, such as
+`message`, parameter entries in `errors`, and validator messages in
+self-description. Self-description parameter `label` and `description` values
+may also be localized. The envelope shape does not change and clients must
+continue to treat these values as strings.
+
+# Description format
+In this document, the self-description is encoded in JSON. However, it can
+be encoded in any of the supported output formats.
+
+## API version
+
+<a href="/doc/protocol.png">
+<img src="/doc/protocol.png"
+     alt="Diagram representing the structure of an API version"
+	 width="600">
+</a>
+
+API version is described as:
+
+    {
+        "authentication": {
+            ... authentication methods ...
+        },
+        "resources": {
+            ... resources ...
+        },
+        "meta": {
+            "namespace": "_meta"
+        },
+        "help": "/<version>/"
+    }
+
+See appropriate section for detailed description of each section.
+
+## Authentication
+HaveAPI defines an interface for implementing custom authentication methods.
+HTTP basic and token authentication is built-in.
+
+Authentication methods can be set per API version. They are a part of
+the self-description, but must be understood by the client.
+The client can choose whichever available authentication method he prefers.
+
+### HTTP basic authentication
+HTTP basic authentication needs no other configuration, only informs about its presence.
+
+    "basic": {}
+
+HTTP basic authentication does not support multi-factor authentication.
+
+### Token authentication
+Token authentication contains resource ``token``, that is used to acquire
+and revoke tokens.
+
+Tokens are acquired by action ``request``, in which the client provides arbitrary
+login credentials. If the login credentials match, the server either concludes
+the authentication process, or multiple authentication steps may be necessary.
+
+For single-step authentication processses, action ``request`` returns the
+token and its validity period. If multiple authentication steps are necessary,
+the server signals this by returning ``complete = true``. The client then has
+to call the next authentication step, which is an action on the ``token``
+resource, as returned in ``next_action``.
+
+Tokens are returned in both cases. If the authentication is finished, the token
+is then used for authenticating further requests. If the authentication continues,
+the token is used to authenticate the next authentication request, which then
+returns another token.
+
+After the authentication is complete, acquired tokens can be renewed using action
+``renew`` and revoked by calling the ``revoke`` action.
+
+    "token": {
+        "http_header": "<name of HTTP header to transfer token in, by default X-HaveAPI-Auth-Token>",
+        "query_parameter": "<name of query parameter for token, by default auth_token>",
+        "resources": {
+            "actions": {
+                "request": {
+                    ...
+                    "input": {
+                        ...
+                        "parameters": {
+                            "user": ...
+                            "password": ...
+                            "lifetime": ...
+                            "interval": ...
+                        },
+                        ...
+                    },
+                    "output": {
+                        ...
+                        "parameters": {
+                            "token": ...
+                            "valid_to": ...
+			    "complete": true/false
+			    "next_action": ...
+                        },
+                        ...
+                    },
+                    ...
+                 }
+                "revoke": ...
+            }
+        }
+    }
+
+The format for ``resources`` section is the same as for any other resource.
+
+## Resources
+Each resource is described as:
+
+    "<resource_name>": {
+        "description": "Some description that explains everything",
+        "actions": {
+            ... actions ...
+        },
+        "resources": {
+            ... nested resources ...
+        }
+    }
+
+## Actions
+Every action is described as:
+
+    "<action_name>": {
+        "auth": true|false,
+        "description": "Describe what this action does",
+        "aliases": ["list", "of", "aliases"],
+        "blocking": true|false,
+        "input":  {
+            "layout": "layout type",
+            "namespace": "namespace name",
+            "parameters": {
+                ... parameters ...
+            }
+        },
+        "output": {
+             "layout": "layout type",
+             "namespace": "namespace name",
+             "parameters": {
+                  ... parameters ...
+              }
+        },
+        "examples": [
+            ... list of examples ...
+        ],
+	"meta": ... metadata ...,
+        "path": "Path for this action",
+        "method": "HTTP method to be used",
+        "help": "Path to get this very description of the action"
+    }
+
+### Layouts
+Layout type is specified for input/output parameters. Thanks to the layout type,
+clients know how to send the request and how to interpret the response.
+
+Defined layout types:
+
+ - object - mainly the response is to be treated as an instance of a resource
+ - object_list - list of objects
+ - hash - simply a hash of parameters, it is to be treated as such
+ - hash_list - list of hashes
+
+In client libraries, the ``object`` layout output usually results in returning
+an object that represents the instance of the resource. The parameters are defined
+as object properties and the like.
+
+### Namespace
+All input/output parameters are put in a namespace, which is usually
+the name of the resource.
+
+For example:
+
+    {
+        "user": {
+            ... parameters ...
+        }
+    }
+
+## Parameters
+There are two parameter types.
+
+### Data types
+The type can be one of:
+
+ - String
+ - Text
+ - Boolean
+ - Integer
+ - Float
+ - Datetime
+
+#### Typed input coercion and validation
+Typed input parameters MUST be validated strictly by servers and clients. Query parameters arrive as
+strings and must be parsed before validation. Canonical rules and examples are documented in
+[Typed input validation](typed-input-validation.md).
+Explicit `null` is allowed only for parameters marked `nullable` (typically optional) and MUST
+be preserved by clients (send JSON `null`) so the server can distinguish between omitted and
+explicitly cleared values. When using query-string input, explicit `null` is encoded as an
+empty string; servers treat empty/whitespace as `null` only for nullable typed parameters.
+For non-nullable parameters, empty strings are validated normally (string/text can be empty,
+other types reject empty).
+
+Example (query string, optional typed param set to `null`):
+
+    GET /resource/action?resource[dt]=
+
+        "<parameter_name>": {
+            "required": true/false/null,
+            "nullable": true/false,
+            "label": "Label for this parameter",
+            "description": "Describe it's meaning",
+            "type": "<one of the data types>",
+            "validators": ... validators ...,
+            "default": "default value that is used if the parameter is omitted",
+            "protected": true/false
+        }
+
+
+#### Validators
+Every parameter has its own validators. Any of the following validators
+may be present. Input value must pass through all validators in order
+to be considered valid.
+
+##### Acceptance
+Used when a parameter must have one specific value.
+
+    "accept": {
+        "value": <value to accept>,
+        "message": "has to be <value>"
+    }
+
+##### Presence
+The parameter must be present. If `empty` is `false`, leading and trailing
+whitespace is stripped before the check.
+
+    "present": {
+        empty: true/false,
+        message: "must be present"
+    }
+
+##### Confirmation
+Used to confirm that two parameters have either the same value or not have the
+same value. The former can be used e.g. to verify that passwords are same
+and the latter to give two different e-mail addresses.
+
+    "confirm": {
+        "equal": true/false,
+        "parameter": <parameter_name>,
+        "message": "must (or must not) be the same as <parameter_name>"
+    }
+
+##### Inclusion
+The parameter can contain only one of given options.
+
+    "include": {
+        "values": ["list", "of", "allowed", "values"],
+        "message": "%{value} cannot be used"
+    }
+
+If the `values` are a list, than it is a list of accepted values.
+If the `values` are a hash, the keys of that hash are accepted values,
+values in that hash are to be shown in UI.
+
+    "include": {
+        "values": {
+            "one": "Fancy one",
+            "two": "Fancy two"
+        },
+        "message": "%{value} cannot be used"
+    }
+
+##### Exclusion
+The parameter can be set to anything except values listed here.
+
+    "exclude": {
+        "values": ["list", "of", "excluded", "values"],
+        "message": "%{value} cannot be used"
+    }
+
+##### Specific format
+If `match` is true, the parameter must pass given regular expression.
+Otherwise it must not pass the regular expression.
+
+    "format": {
+        "rx": "regular expression",
+        "match": true/false,
+	"description": "human-readable description of the regular expression",
+        "message": "%{value} is not in a valid format"
+    }
+
+##### Length
+Useful only for `String` and `Text` parameters. Checks the length of given string.
+It may check either
+
+ - minimum
+ - maximum
+ - minimum and maximum
+ - constant length
+
+The length validator must therefore contain one or more checks, but cannot
+contain both min/max and equality.
+
+Length range:
+
+    "length": {
+        "min": 0,
+        "max": 99,
+        "message": "length has to be in range <0,99>"
+    }
+
+Constant length:
+
+    "length": {
+        "equals": 10,
+        "message": "length has to be 10"
+    }
+
+##### Numericality
+Numericality implies that the parameter must be a number, i.e. `Integer`, `Float`
+or `String` containing only digits. It can check that the number is in a specified
+range and can provide a step. The validator can contain one or more of these conditions.
+
+    "number": {
+        "min": 0,
+        "max": 99,
+        "step": 3,
+        "mod": 3,
+        "even": true/false,
+        "odd": true/false
+    }
+
+##### Custom validation
+Custom validation cannot be documented by the API. The developer may or may not
+provide information that some non-documented validation takes place. The documentation
+contains only the description of the validations that may be shown to the user,
+but is not evaluated client-side, only server-side.
+
+    "custom": "description of custom validation"
+
+### Resource association
+This is used for associations between resources, e.g. car has a wheel.
+
+    "<parameter_name>": {
+        "required": true/false/null,
+        "nullable": true/false,
+        "label": "Label for this parameter",
+        "description": "Describe it's meaning",
+        "type": "Resource",
+        "resource": ["path", "to", "resource"],
+        "value_id": "<name of a parameter that is used as an id>",
+        "value_label": "<name of a parameter that is used as a value>",
+        "value": {
+            "path": "Path to 'show' action of associated resource",
+            "method": "HTTP method to use",
+            "help": "Path to get the associated resource's 'show' description"
+        },
+        "choices": {
+            "path": "Path to action that returns a list of possible associations",
+            "method": "HTTP method to use",
+            "help": "Path to description of the list action"
+        }
+    }
+
+The _resource_ type also has a different output in action response. It returns
+a hash containing associated resource ID and its label, so that clients
+can show the human-friendly label instead of just an ID.
+
+For input parameters of type `Resource`, empty/whitespace input is treated as
+`null`/omitted only when the parameter is nullable. Required resource parameters
+still reject empty/whitespace input.
+
+    "<parameter_name>": {
+        "<value of value_id from description>": <resource id>,
+        "<value of value_label from description>": "<label>"
+    }
+
+## Examples
+Examples are described in a generic way, so that every client can
+render them according to its syntax.
+
+    {
+        "title": "A title",
+        "path_params: [ ... array of integers ... ],
+        "request": {
+            ... a hash of request parameters ...
+        },
+        "response": {
+            ... a hash of response parameters ...
+        },
+        "status": true/false,
+        "message": "Message explaining an error if it occurs",
+        "errors": {
+            "<parameter>": [ ... array of errors ... ],
+        },
+        http_status: 200,
+        "comment": "Description of the example"
+    }
+
+## Metadata
+Metadata can be global and per-object. Global metadata are sent once for each
+response, where as per-object are sent with each object that is a part of the
+response.
+
+    {
+        "global": {
+            "input": ... parameters or null ...,
+            "output: ... parameters or null ...
+        } or null,
+
+        "object": {
+            "input": ... parameters or null ...,
+            "output: ... parameters or null ...
+        } or null,
+    }
+
+Per-object metadata may include `path_params`, an array of URL parameters that
+clients can use to prepare actions on the returned object. This field is
+optional. Servers may omit it when the response does not expose the identifiers
+that would be needed to reconstruct those URL parameters.
+
+## Blocking mode
+Blocking mode is for actions whose execution takes a long time. Clients can monitor
+progress of such actions and even cancel their execution.
+
+The blocking action returns its result as usual, but provides a unique identifier using
+which clients can check its status via the `ActionState` resource. The state identifier
+is passed through global output metadata in a parameter called `action_state_id`.
+Resource `ActionState` is a part of the API's documentation and is the standard interface
+for browsing and manipulating currently active blocking actions.
+
+An action is blocking if parameter `blocking` in its description is `true` and if
+`action_state_id` is present in its metadata after each call. This allows actions
+to be blocking only when needed.
+
+## List API versions
+Send request ``OPTIONS /?describe=versions``. The description format:
+
+    {
+        "versions": [1, 2, 3, ... list of versions],
+        "default": <which version is default>
+    }
+
+## Describe default version
+Send request ``OPTIONS /?describe=default`` the get the description
+of the default version.
+
+## Describe the whole API
+It is possible to get self-description of all versions at once.
+
+Send request ``OPTIONS /``. The description format:
+
+    {
+        "default_version": <which version is default>,
+        "versions": {
+            "default": ... full version self-description ...,
+            "<version>": ... full version self-description,
+             ... all other versions ...
+        }
+    }
+
+# Authorization
+Actions may require different levels of authorization. HaveAPI provides means for
+implementing authorization, but it is not self-described.
+
+If the user is authenticated when requesting self-description, only allowed
+resources/actions/parameters will be returned.
+
+# Input/output formats
+For now, the only supported input format is JSON.
+
+Output format can be chosen by a client. However, no other format than JSON is built-in.
+The output format can be chosen with HTTP header ``Accept``.
+
+# Request
+Action path and HTTP method the client learns from the self-description.
+
+Example request:
+
+    POST /users HTTP/1.1
+    Content-Type: application/json
+    Accept: application/json
+    Connection: Close
+
+    {
+        "user": {
+            "login": "mylogin",
+            "name": "Very Name",
+            "role": "admin"
+        }
+    }
+
+# Response
+Clients know how to interpret the response thanks to the layout type they learn
+from the self-description.
+
+Example response to the request above:
+
+    Content-Type: application/json
+
+    {
+        "status": true,
+        "response": {
+            "user": {
+                "id": 1,
+                "login": "mylogin",
+                "name": "Very Name",
+                "role": "admin"
+            }
+        },
+        "message": null,
+        "errors: null
+    }

data/doc/typed-input-validation.md

@@ -0,0 +1,113 @@
+# Typed input validation
+
+## Overview
+HaveAPI parameters declare a `type` (String, Text, Integer, Float, Boolean, Datetime, plus Resource).
+Servers and clients MUST validate typed input parameters strictly.
+Invalid values MUST NOT be silently coerced into defaults like `0`, `0.0`, or `false`.
+
+## General rules
+- Scalars only for scalar types: arrays/lists and objects/hashes are invalid for scalar types.
+- `null`/`nil` means "value omitted" for validation purposes (server defaults may apply),
+  but explicit `null` is a valid value only for parameters marked `nullable` (usually optional).
+  Clients MUST preserve explicit `null` (send it as JSON `null`) so actions can distinguish
+  "omitted" vs "explicitly cleared".
+- Empty strings (`""` or whitespace-only strings) are invalid for Integer, Float, Boolean, and Datetime.
+  For nullable typed parameters (including Resource IDs), empty/whitespace is treated as
+  `null`/omitted, which lets query-string inputs represent explicit `null`.
+- Client-side validation is recommended; the server is authoritative.
+
+Query-string example (explicit `null` for nullable typed param):
+
+    GET /resource/action?resource[dt]=
+
+The empty value is treated as `null` for nullable typed parameters.
+
+## Per-type rules with examples
+
+### Integer
+Accept:
+- JSON integer (e.g. `12`, `-7`)
+- string matching base-10 integer `^[+-]?\d+$` after trim (e.g. `"42"`, `"+5"`)
+- float that is finite and integral (e.g. `12.0`)
+
+Reject:
+- non-numeric strings (`"abc"`, `"12abc"`)
+- decimal strings (`"12.0"`) and non-integral floats (`12.3`)
+- empty/whitespace string
+
+### Float
+Accept:
+- JSON integer or float (finite only)
+- string matching a full float token after trim, including exponent (e.g. `"1e3"`, `"-0.5"`)
+
+Reject:
+- non-numeric strings
+- empty/whitespace string
+- non-finite values (`NaN`, `Infinity`)
+
+Note: integers are accepted for Float and become floats.
+
+### Boolean
+Accept:
+- JSON boolean
+- integer `0`/`1`
+- string tokens (case-insensitive, after trim):
+  - truthy: `true`, `t`, `yes`, `y`, `1`
+  - falsy: `false`, `f`, `no`, `n`, `0`
+
+Reject:
+- empty/whitespace string
+- unknown strings (`"maybe"`)
+- numbers other than 0/1
+
+### Datetime
+Accept (wire format): ISO 8601 date/datetime strings:
+- `YYYY-MM-DD`
+- `YYYY-MM-DDTHH:MM(:SS(.sss)?)?(Z|+HH:MM|-HH:MM|+HHMM|-HHMM)`
+
+Examples: `"2020-01-31"`, `"2020-01-31T10:20Z"`, `"2020-01-31T10:20:30.123-0500"`.
+
+Reject:
+- empty/whitespace string
+- non-ISO formats (`2020/01/01`)
+- invalid calendar dates (`2020-02-30`)
+
+Note: some clients may accept native Date/Time objects and serialize to ISO 8601.
+
+### String / Text (rule 6.B)
+Accept:
+- scalar values (string, number, boolean) and coerce to string
+
+Reject:
+- arrays/lists
+- objects/hashes
+
+### Resource
+Wire inputs are resource identifiers.
+
+Accept:
+- integer id
+- digit-string id after trim
+- (some clients) ResourceInstance -> uses its `id`
+- empty/whitespace string is treated as `null`/omitted when the parameter is nullable
+
+Reject:
+- empty/whitespace string for required parameters
+- non-digit strings
+- negative ids
+
+If the server attempts to resolve the resource and it does not exist, it MUST become a validation error
+("resource not found"), not a 500.
+
+## Error reporting expectations
+- On the server, invalid typed values are reported as parameter validation errors ("input parameters are not valid").
+- Clients should fail fast locally when possible and report per-parameter errors.
+
+Recommended canonical messages used by clients:
+- `not a valid integer`
+- `not a valid float`
+- `not a valid boolean`
+- `not in ISO 8601 format`
+- `not a valid string`
+- `not a valid resource ID`
+- `cannot be null`

data/haveapi.gemspec

@@ -15,7 +15,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= #{File.read('../../.ruby-version').strip}"
 
   s.add_dependency 'activesupport', '>= 7.1'
-  s.add_dependency 'haveapi-client', '~> 0.29.8'
+  s.add_dependency 'haveapi-client', '~> 0.29.9'
   s.add_dependency 'i18n', '>= 1.6', '< 2'
   s.add_dependency 'json'
   s.add_dependency 'mail'