apiary.apib

FORMAT: 1A
HOST: http://api.ehealth.gov.ua/

# ADMIN API MAN TEMPALATES

**Версія: 2.0.0**

It is capable to store templates (in `iex`, `mustache`) or `markdown`, render it and dispatch in PDF, JSON or HTML formats.


## Introduction

Man consists of two main parts:

- [REST API back-end](https://github.com/Nebo15/man.api) that allows to manage and render Templates;
- [Management UI](https://github.com/Nebo15/man.web) that simplifies configuration and templates management.

## Use Cases

- Rendering reports;
- Central control over Email or/and SMS templates;
- PDF/HTML printout forms generation;
- Rendering HTML pages over API.

## License

Man is distributed under MIT license. See [README.md](https://github.com/Nebo15/man.api/blob/master/LICENSE.md) in GitHub repositories.

## UI

![UI Demo](https://github.com/Nebo15/man.web/raw/master/docs/images/ui-animated.gif)

## Performance

We encourage you to perform your own tests, because synthetic results are far from real life situation. We provide them only as starting point in understanding Man's performance.

### Test environment

* MacBook Pro (15-inch, 2016)
* CPU 2,7 GHz Intel Core i7
* RAM 16 ГБ 2133 MHz LPDDR3
* Man v0.1.16 and PostgreSQL v9.6.2 running in Nebo15 Docker contianers (listed below);
* ApacheBench v2.3;
* wkhtmltopdf v0.12.4 (with patched qt);
* Log level: info.

### Results

| **Metric**/**Template Syntax**                          | **Mustache** | **Markdown** | **Mustache with PDF format** | **Mustache with PDF format** **and PDF cache enabled** |
| ------------------------------------------------------- | ------------ | ------------ | ------------- | ------------- |
| Concurrency Level                                       | 50           | 50           | 50            | 50 |
| Time taken for tests                                    | 8.412 sec    | 8.142 sec    | 442.214 sec   | 11.255 sec |
| Complete requests                                       | 10000        | 10000        | 10000         | 10000 |
| Failed requests                                         | 0            | 0            | 0             | 0 |
| Requests per second [#/sec] (mean)                      | **1188.84**  | **1228.25**  | **22.61**     | **888.52** |
| Time per request                                        | 42.058 [ms]  | 40.708 [ms]  | 2211.070 [ms] | 56.274 [ms] |
| Time per request (mean, across all concurrent requests) | 0.841 [ms]   | 0.814 [ms]   | 44.221 [ms]   | 1.125 [ms] |

Full console output is available in [`pertest.md`](https://github.com/Nebo15/man.api/blob/master/docs/perftest.md).

### PDF Output Cache

Since generating PDF is slow, Man allows to cache `wkhtmltopdf` output.

This cache can be used when you have less than 1000 of different templates variations (eg. markdown templates, or mustache templates but all variables are continuous or enums). To enable it simply set `CACHE_PDF_OUTPUT=true` in your environment.

Enabling cache when output variety is high will hurt your performance (cache will always be cold, since it's based on HTML checksum) and may lead to node crashes (ETC table may overflow).

## Setup Guide

### Docker

Easiest way to deploy Man is to use docker containers.
We constantly are releasing pre-built versions that will reduce time to deploy:

- [Back-End Docker container](https://hub.docker.com/r/nebo15/man_api/) (~239 MB);
- [PostgreSQL Docker container](https://hub.docker.com/r/nebo15/alpine-postgre/) (~16 MB);
- [UI Docker container](https://hub.docker.com/r/nebo15/man-web/) (~108 MB).

They are built on top of Alpine Linux, to reduce container size and memory consumption.

### Heroku

Template allows to deploy Man to Heroku just in minute (and use it for free within Heroku tiers):

[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/nebo15/man.api)

## Common errors

> I'm getting HTTP 400 (Mailformed JSON) responses.

Make sure that JSON is valid with [JSON Formatter](jsonformatter.curiousconcept.com).
If request is valid, probably your request body structure is invalid. In most cases you forgot to send root `template` object when updating Templates.

> I'm getting HTTP 415 responses.

You MUST always set `Content-Type: application/json` header when requesting Man's API.

## Templates [/templates]

### Search for a Template [GET /templates{?limit,starting_after,ending_before,labels,title}]

+ Parameters
    + labels: `label-name1,label-name2` (string, optional) - Label names to filter Templates list.
    + limit: 20 (number, optional) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
    + starting_after: 56c31536a60ad644060041af (string, optional) - A cursor to fetch next page. Taken from collection response.
    + ending_before: 56c31536a60ad644060041aa (string, optional) - A cursor to fetch previous page. Taken from collection response.
    + title: Signup (string, optional) - Substring search for a title.

+ Response 200 (application/json)
    + Attributes (Response_Collection)
        + data (array[Template_Response], fixed-type)

### Create Template [POST]

+ Request (application/json)
    + Attributes (object)
        + template (Template)

+ Response 201 (application/json)
    + Headers
    
            Location: /templates/58e2278a84092e61700041a7
            
    + Attributes (Response_OK)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (Template_Response)

### Get Template by ID [GET /templates/{id}]

+ Parameters
    + id: 58e2278a84092e61700041a7 (string) - Template ID

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (Template_Response)

### Replace Template [PUT /templates/{id}]

+ Parameters
    + id: 58e2278a84092e61700041a7 (string) - Template ID

+ Request (application/json)
    + Attributes (object)
        + template (Template)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (Template_Response)

### Update Template [PATCH /templates/{id}]

+ Parameters
    + id: 58e2278a84092e61700041a7 (string) - Template ID

+ Request (application/json)
    + Attributes (object)
        + template (object)
            + body: `<h1>{{user_name}}</h1>` (string, optional)

+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (Template_Response)
            + body: `<h1>{{user_name}}</h1>` (string, required)

### Delete Template [DELETE /templates/{id}]

+ Parameters
    + id: 58e2278a84092e61700041a7 (string) - Template ID

+ Request (application/json)
+ Response 204 (application/json)

### Render Template [POST /templates/{id}/actions/render]

#### Localization

You can pass `Accept-Language: <localization>` header or `localization` request attribute.

In case both fields are specified, HTTP header will be preffered.

When there is only one locale set for a template, localization attribute is optional and the onlymost list element will be counted as default.

#### Available variables

Template can use any variables from request attributes as global scoped objects `{{var_name}}` and all available localization fields within `l10n` object `{{l10n.localized_key}}`.

#### Validation

Rendering request is validated by JSON Schema that is set in Template.

#### Output Format

Output format is controlled by `Accept: <format>` header.

**Supported formats:**

| `Accept` (format)     | Response `Content-Type`           | Description |
| --------------------- | --------------------------------- | ----------- |
| `text/html` (default) | `text/html; charset=utf-8`        | Raw HTML Page. |
| `application/json`    | `application/json; charset=utf-8` | JSON object with `body` and `params` fields: `{"body":"<h1>Hello Alex, in en_US</h1>"}` |
| `application/pdf`     | `application/pdf`                 | PDF document rendered from HTML. |

**Notice.** You can use `params` field from JSON response to localize fields that should be used elsewhere, even if template does not contain matched fields. For example, you can localize email subjects in this way.

**Warning!** Format is applied only when there was no errors during rendering, otherwise - response will be always in json format with `Content-Type: application/json`.

+ Parameters
    + id: 58e2278a84092e61700041a7 (string) - Template ID

+ Request (application/json)
    + Headers

            Accept: text/html
            Accept-Language: en-US

    + Attributes (object)
        + locale: en_US (string, optional) - Locale of template that should be rendered. Required when `Accept-Language` header is not set.
        + format: `text/html` (enum, optional) - Format of output.
            - `text/html` (string) - Render HTML page.
            - `application/json` (string) - Render HTML page and returin it in JSON object.
            - `application/pdf` (string) - Render PDF from HTML template.
            - Default: text/html
        + user_name: Alex (string) - Template data that should be used by rendering engine.

+ Response 200 (text/html)
    + Body

            <h1>Hello Alex, in en_US</h1>

+ Response 404 (application/json)
    + Attributes (`Response_Error`)
        + meta
            + code: 404
        + error
            + type (enum, required)
                - `locale_not_found` (string) - Specified locale is not set for a template.
                - `not_found` (string) - Template not found.

+ Response 422 (application/json)
    + Attributes (`Response__Error_ValidationFailed`)

## Labels Collection [/labels]

### Get all defined labels [GET]

+ Request (application/json)
+ Response 200 (application/json)
    + Attributes (Response_OK)
        + data (array[string], fixed-type)
            + `group/emails` (string, required)
            + `action/signup` (string, required)

# Data Structures
## Responses
### `Response_Collection`
+ meta (Response__Meta, fixed-type)
+ data (array[], fixed-type)
+ paging (Response__Pagination, fixed-type)

### `Response_OK`
+ meta (Response__Meta, fixed-type)
+ data (object, fixed-type)

### `Response_Error`
+ meta (Response__Meta, fixed-type)
    + code: 400 (number)
+ error (Response__Error, fixed-type)

### `Response__Meta`
+ code: 200 (number) - HTTP response code.
+ url: http://example.com/resource (string) - URL to requested resource.
+ type (enum) - Type of data that is located in `data` attribute.
    - object (string) - `data` attribute is a JSON object.
    - list (string) - `data` attribute is a list.
+ code: 200 (number) - HTTP response code.
+ `idempotency_key`: `idemp-ssjssdjoa8308u0us0` (string, optional) - [Idempotency key](http://docs.apimanifest.apiary.io/#introduction/optional-features/idempotent-requests). Send it trough `X-Idempotency-Key` header.
+ `request_id`: `req-adasdoijasdojsda` (string) - [Request ID](http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/request-id). Send it with `X-Request-ID` header.

### `Response__Error`
+ type: type_atom (string) - Atom that represents error type.
+ message: Error description (string) - Human-readable error message. This is for developers, not end-users.

### `Response__Error_DuplicateEntity`
+ type: `object_already_exists` (string) - Atom that represents error type.
+ message: This API already exists (string) - Human-readable error message. This is for developers, not end-users.

### `Response__Error_ValidationFailed`
+ type: validation_failed (string) - type of an error.
+ message: Validation failed. You can find validators description at our API Manifest: http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/errors. (string)
+ invalid (array)
    + `entry_type`: `json_data_proprty` (string) - Type of error.
    + entry: $.cvv (string) - JSON Path to an invalid property.
    + rules (array)
        + rule: required (string) - String constant that represents validation rule type. List of all types can be found in [API Manifest](http://docs.apimanifest.apiary.io/#introduction/interacting-with-api/errors).
        + params (array) - Validation Parameters.

### `Response__Pagination`
+ limit: 20 (number) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
+ cursors (object)
    + `starting_after`: 56c31536a60ad644060041af (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
    + `ending_before`: 56c31536a60ad644060041aa (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
+ size: 1000 (number) - Total number of objects in collection.
+ has_more: false (boolean) - Is this collection have more data to load in the same style as last request loaded it.

## Templates
### Template
+ title: `Sign-Up Email` (string, required) - Template UI title with max length 255 characters.
+ description: `Email that is sent on signup process` (string, optional) - Template UI description with max length 510 characters.
+ syntax: `mustache` (enum, optional) - Syntax processor for a template
    + `mustache`
    + `markdown`
+ body: `<h1>{{l10n.hello}} {{user_name}}, in {{locale}}</h1>` (string, required) - Template that should be rendered with `syntax` processor.
+ locales (array[Template__Locale], optional) - Locale variables that can be used for multilangual templates.
+ labels (array[string], optional) - List of strings. Max length for element is 100 characters.
    + `group/emails` (string)
    + `action/signup` (string)
    + `other_tag` (string)
+ validation_schema (object, optional) - JSON Schema to validate requests to the template.

### `Template_Response` (Template)
+ id: 58e2278a84092e61700041a7 (string, optional)
+ created_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ updated_at: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Template__Locale`
+ code: en_US (string, required) - Locale for defined template
+ params (object, required) - Localized attributrs.
    + hello: Hello (string, optional) - Localized variable.