79aaf92463a93a91661d4a8ed5249aba4ddfa7d1 — Mendel E 1 year, 5 months ago c6db0f6
Add some api documentation
1 files changed, 105 insertions(+), 0 deletions(-)

A api.md
A api.md => api.md +105 -0
@@ 0,0 1,105 @@
## Endpoints

Being that this uses `http.ServerMux`, if you need to avoid caching you can add
to your endpoint path, and it will still reach its correct handler. You can see
the [docs](https://golang.org/pkg/net/http/#ServeMux) to learn more.


This is the main endpoint. You can pass it options as url query params, and it
will return a png image.

GET /web/

This endpoint will return an HTML file, with [OpenGraph](https://ogp.me) meta
tags, and a link to the generated image in `og:image`. It will take the same
options as `GET /`, plus some specific to the meta tags.

## Options

Options can be passed as URL query params. The options are described here as:

name	type	default_value

All options are, optional. There should always be a fallback value.

width	int	100
height	int	100

Set the width and height of the image. If only `width` is passed, `height` will
be set to its value.

TODO: If only `height` is passed, set `width` to its 16:9 equivalent (ie `width = height / 9 * 16`).

color	[]string	[]string{"#242933", "#eceff4"}

Set the colors to be used for the image. Hex strings can be in any of the
following formats: `rgb`, `rgba`, `rrggbb`, `rrggbbaa`. It is not
case-sensitive, hashes (`#`) at the start will be ignored, and `alpha` will be
set to `255` (ie `ff`) if not passed.  You can pass more than one color, and
they will be used as needed.

desc	string	""

_This option is only available on the `/web/` endpoint._

Set the `og:description` content.

## Other options (WIP)

pattern	string	"plain"

Set the pattern for the image drawing. The different patterns are:

- `plain`: just a plain, one color, background.
- `diagonal`: split diagonally, two colors.
- `vertical`: split vertically, two colors.
- `horizontal`: split horizontally, two colors.

## Text options (WIP)

text	string	""

Set the text content to be rendered on the image. The text color will be the
last passed `color` param.

font	string	""

Set the font family for the text.

size	int

Set the font size for the text.
TODO: default value, dpi?

center	string	"height"

Text can be set centered in two ways: on the actual `height` of the text, which
can vary depending on the letter (ie, `l` is a lot taller than `_`), or on a
consistent (among other letters in its font) `baseline`.