boxdox / placeholder-api

a RESTful service for placeholder text and images!

Placeholder API

A RESTful service for generating dummy text and placeholder images.
Built with Express and TypeScript.

Usage

Dummy Text:

GET request on /text with optional Query Parameters:

• type: word, sentence or paragraph. Defaults to paragraph.
• amount: Number. Defaults to 3.
• format: raw, html or json. Defaults to html.

To generate 2 paragraphs in json, GET /text?amount=5&format=json, returns:

{
    "text": "Ullam adipiscing quasi ea perspiciatis nostrum aut. Anim voluptas unde laudantium iure do corporis rem. Nesciunt laboris amet excepteur, ipsa suscipit qui pariatur perspiciatis. Amet exercitation accusantium nisi ex. Id dolore inventore quaerat eum ut natus. Adipiscing nesciunt exercitation id unde, voluptas porro.\nQuae quia fugiat eius porro. Sit omnis duis cupidatat sunt consequat fugit aute. Nulla ad ex consectetur adipiscing pariatur sed aliquam. Adipiscing enim exercitationem autem nihil sit illo dolorem. Ex ullamco ullam sed laborum adipiscing, illo numquam. Amet adipiscing explicabo eu proident. Neque sequi occaecat est, nisi.",
    "count": "2 paragraphs, 89 words generated",
    "credits": "https://github.com/boxdox/placeholder-api",
    "support": "https://www.buymeacoffee.com/blamemycode"
}

Dummy Image

Image take a different request approach. GET request on /image/:width/:height?/:format?/?text=Your optional text. In this, width parameter is required.

Route parameters:

• width: Number, required. Should be between 1 and 4000
• height: Number, optional. Should be between 1 and 4000. If not specified, it is set equal to width.
• format: jpeg, png or bmp, optional. Defaults to jpeg.

There is a query parameter as well, if you want to customize the text in the image:

• text: String, optional. Defaults to width x height

Note: Due to an issue in librsvg, text centering and wrapping is not possible at the moment. I have approximated the text to be vertically centered, I will update the code once the library is fixed. You can read about it here.

Getting Images

For a square image 300px wide, GET /image/300:

To get a image of size 500x200 in png with text saying "Howdy!", GET /image/500/200/png?text=Howdy!:

Development

Fork the repo or clone it locally using:

git clone https://github.com/boxdox/placeholder-api.git
cd placeholder-api

Rename (or make a copy) the .env.sample to .env and modify as per requirement:

cp .env.sample .env

Install the dependencies and start the development server:

yarn install
yarn dev

Create a build by running:

yarn build

Deployment

You can either use a PaaS like Heroku or you can build the Docker image.

To build the docker image, run:

chmod +x ./build-docker.sh
./build-docker.sh

Licence

MIT 2020