Qual ID is a RESTful API that returns qualitative ID's. A qualitative ID is a unique signifier that is readable and understandable to humans. This serves the same purpose as any other ID, while also being much nicer to deal with and much easier to remember.
The Qual ID REST API can be accessed using the URL
https://qual-id.herokuapp.com/
categories
ParameterTo get Qual IDs from the REST API, supply categories, separated by hyphens, to the /get/
endpoint. For example:
https://qual-id.herokuapp.com/get/?categories=food-animal
which would give a JSON object, with results in the form of a food followed by an animal. e.g.
{ "data": ["lemon-lobster"] }
In addition to defined categories, the word random
can be used, which will use a random category in it's place.
number
ParameterAs well as the categories
parameter, the number
parameter can also be used, to determine how many Qual ID's will be returned. For example:
https://qual-id.herokuapp.com/get/?categories=food-animal&number=3
which would return a JSON object containing 3 Qual ID's matching the food-animal
pattern. e.g.
{ "data": ["lemon-lobster", "cookie-whale", "egg-lizard"] }
format
ParameterThe format
parameter can also be used to determine in what format the results will be returned. This value is, by default, "json", but can also be "csv", which gives results in simple comma-separated format. e.g.
https://qual-id.herokuapp.com/get/?categories=food-animal&format=csv
which would return
"lemon-lobster"
group
ParameterBy default, all categories are avaiable, but if you want a more predictable range of categories when using random
, you can supply a group
. A group is a subset of all the categories, and random
will only return a category from this group. Examples of groups are "all" (which is the default group), "minimal" and "neutral". e.g.
https://qual-id.herokuapp.com/get/?categories=food-random&group=minimal
The /categories/
endpoint returns a list of categories that can are accepted by the 'get' endpoint. For example:
https://qual-id.herokuapp.com/categories/
would return a JSON object containing the list of category names, e.g.
{ "data": ["animal", "food", ...] }
The 'categories' endpoint also accepts a group
paramter.
The Qual ID CLI allows qual ID's to be generated locally. It only requires python3
to be installed.
To use the Qual ID CLI, run
curl -s "https://raw.githubusercontent.com/gabrielbarker/qual-id/main/bin/install.sh"|sh -s <INSTALL_DIRECTORY>
where <INSTALL_DIRECTORY>
is the path of a directory that is part of your terminal path. Note: If omitted, the current directory is used
Or alternatively, download the latest release tar file. Then unzip, and place the qual_id
directory and qid
executable in a directory that is part of your terminal path.
To view the help for qid
, run
qid --help
This will give you the basics, but what follows is a more detailed description of some of qid
's features.
To generate a qual ID, run
qid --categories flower bread
where "flower" and "bread" can be replaced by the names of up to 5 categories. The above command will return, for example,
poppy-pumpernickel
Note: the CLI has 'csv' format by default.
The same parameters available in the REST API are available in the CLI. The following is an example of a command using all possible options:
qid --categories flower cake --group neutral --format json --number 3
or with shortened flags:
qid -c flower cake -g neutral -f json -n 3
returning, for example,
{"data": ["chrysanthemum-crumpet", "wisteria-tart", "saffron-panettone"]}
Unique to the CLI is the info subcommand. info allows you to see possible options for all parameters, and what values are contained in a given category.
To see a list of all categories, run
qid info --category
To see a list of all groups, run
qid info --group
To see a list of all categories in a given group, run
qid info --group minimal
where minimal can be any group name.
To see a list of all values for a given category, run
qid info --category animal
where animal can be any category name.
To see a list of all available formats, run
qid info --format
This repo strongly welcomes all contributions! Whether to documentation, assets, data, or code. There are standing issues to add values to existing categories, or add new categories all together. You can see the full contribution guide here.