is a set of requirements that define a webapp pluggable in a website

Website-component-definition.md

Website component

is a set of requirements that define a report component pluggable in a console site

Definition

A Website component is a Single-page application embedded in a web site, for instance console.example.org.

The main web site is a container: it provides an authentication layer for users, and an access token to fetch data from an API gateway, for instance api.example.org. Both console.example.org and api.example.org are served only over https.

A Website component actually does not require to be embedded, it could work as a standalone client.

Minimal requirements

Follows a list of minimal requirements

1. All data is serialized in JSON format.
2. Can fetch its default state, for instance GET api.example.org/state/myreport.
3. User interaction (like the time range chosen) is defined by a state and can be reproduced.
4. Can store a state, for instance POST api.example.org/report/state.
5. API endpoint to get a state by id, for instance GET api.example.org/state/myreport/123.
6. The state id can be read from the query string, so GET console.example.org/myreport?sid=123 will display a report with the given state.
7. A Website component is versioned in a git repository (see below) and can be imported into the web site via a package manager (like npm and bower).
8. Version should adhere to Semantic versioning.
9. Features should be developed according to TDD process.
10. Code must be linted.

API

A Website component, whatever framework (if any) is implemented with, should take the following parameters:

1. An HTML element it should use to mount on the website page.
2. An API token and domain, retrievied from GET console.example.org/api -> { "token": "xyz123", "baseURL": "https://api.example.net" }. It is recommended to use JWT for authentication.
3. An API endpoint basepath for its state, for instance api.example.net/state/myreport/, in order to
   • fetch default state ²
   • store a state ⁴
   • get a state by id ⁵

Note that the state should contain only metadata. If you need to store raw data, you should use a separated endpoint, for example GET api.example.net/data/myreport which could be passed as a parameter to the init function.

Repository

The git repo should have a structure like the following

• README.md: contains all documentation regarding installation and usage, written in markdown syntax.
• src/: emh, source code.
• test/: unit tests, sample data.
• .editorconfig: to mantain a consistent coding style, see editorconfig.

Any other file in the root folder is allowed if contains metadata: for example .gitignore, .jshintrc, package.json, bower.json, ecc.

You can reference this document in your README.md adding the folllowing snippet to the bottom.

<sub>This repository adheres to <a href="https://gist.github.com/fibo/7ccada6d6af894e6cf7f">Website component definition</sub>

See for example this Redux template.

_{Find last version of this document here.}