Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cheatsnake/xColors-api
π HTTP API for generating & converting colors.
https://github.com/cheatsnake/xColors-api
api colors converter express free herokuapp hex hsl nodejs random rgb ts-node typescript
Last synced: 2 days ago
JSON representation
π HTTP API for generating & converting colors.
- Host: GitHub
- URL: https://github.com/cheatsnake/xColors-api
- Owner: cheatsnake
- License: mit
- Created: 2021-11-13T17:38:06.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2022-11-23T15:42:39.000Z (almost 2 years ago)
- Last Synced: 2024-08-02T05:10:41.713Z (3 months ago)
- Topics: api, colors, converter, express, free, herokuapp, hex, hsl, nodejs, random, rgb, ts-node, typescript
- Language: TypeScript
- Homepage: https://x-colors.yurace.pro
- Size: 63.5 KB
- Stars: 32
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- public-apis - xColors
README
[](https://x-colors.yurace.pro/)
[](https://github.com/cheatsnake/xColors-api/issues)
# :rainbow: xColors API
A free API for generate & convert colors.
## :eyeglasses: Overview
xColors is a completely free service that provides the ability to get random colors and convert them into various color models (HEX, RGB and HSL are supported). All data comes in a convenient JSON format, so you can immediately use them for styling in CSS without additional validation.
## :page_facing_up: API Documentation
### :game_die: Get random color
Get a JSON object that contains a random color in three HEX, RGB and HSL color models at once.
```sh
https://x-colors.yurace.pro/api/random
```
```sh
{
hex: "#CCFB7B",
rgb: "rgb(204, 251, 123)",
hsl: "hsl(82, 51%, 98%)"
}
```
### :art: Get random color with a given hue
You can get random shades of the color you need. For example, using reserved names such as:
[ red, pink, puprle, navy, blue, aqua, green, lime, yellow, orange ]
```sh
https://x-colors.yurace.pro/api/random/blue
```
Instead of reserved words, you can use any number from the range [0, 359] - which corresponds to the [HUE scale](https://en.wikipedia.org/wiki/Hue).
```sh
https://x-colors.yurace.pro/api/random/228
```
### :wrench: Parameters
The number parameter allows you to get an array containing the desired number of random colors.
```sh
?number=3
```
The type parameter allows you to get either only a dark or light shade of color. This allows you to know in advance what font color to use against the background of the resulting color. Usually, the font color is white on dark colors, and black on light colors.
> It works if you have specified the {hue}/{color} you need or use all - for an any color.
```sh
/random/{hue/color/all}?type=dark
```
```sh
/random/{hue/color/all}?type=light
```
### :arrows_counterclockwise: Converting Ρolors
You can freely convert colors between three color models. To do this, use the desired endpoint and use the value parameter to specify the color value of the color model, depending on the selected endpoint.
Convert HEX to RGB
```sh
https://x-colors.yurace.pro/api/hex2rgb?value=FFFFFF
```
Convert HEX to HSL
```sh
https://x-colors.yurace.pro/api/hex2hsl?value=FFFFFF
```
Convert RGB to HEX
```sh
https://x-colors.yurace.pro/api/rgb2hex?value=120-200-30
```
Convert RGB to HSL
```sh
https://x-colors.yurace.pro/api/rgb2hsl?value=120-200-30
```
Convert HSL to HEX
```sh
https://x-colors.yurace.pro/api/hsl2hex?value=300-90-50
```
Convert HSL to RGB
```sh
https://x-colors.yurace.pro/api/hsl2rgb?value=300-90-50
```
## :dart: Examples
```sh
https://x-colors.yurace.pro/api/random?number=10
```
```sh
https://x-colors.yurace.pro/api/random/green?number=10&type=light
```
```sh
https://x-colors.yurace.pro/api/random/123?type=dark&number=2
```
```sh
https://x-colors.yurace.pro/api/hsl2hex/?value=hsl(200,20,10)
```
```sh
https://x-colors.yurace.pro/api/hex2rgb/?value=e2A4bF
```
## :zap: Available Scripts
In the project directory, you can:
- Run the server with Nodemon for development
```sh
npm run dev
```
> The page will reload if you make edits.\
> You will also see any lint errors in the console.\
> Open [http://localhost:5000](http://localhost:5000) to view it in the browser.
- Launch tests
```sh
npm run test
```
- Create a production build
```sh
npm run build
```
- Runs the server of production build
```sh
npm start
```
> Open [http://localhost:5000](http://localhost:5000) to view it in the browser.
## :whale: Docker startup
1. Build docker image from Dockerfile:
```
docker build . -t xcolors
```
2. Create docker container from new image:
```
docker run -p 5000:5000 -d --name xcolors-server xcolors
```