Qual ID

A RESTful API that returns randomly generated, custom qualitative ID's

Using the API • Using the CLI • Contributing • License

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.

Using The API

The Qual ID REST API can be accessed using the URL

https://qual-id.herokuapp.com/

The 'get' Endpoint

The categories Parameter

To 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.

The number Parameter

As 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"] }

The format Parameter

The 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"

The group Parameter

By 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

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.

Using The CLI

The Qual ID CLI allows qual ID's to be generated locally. It only requires python3 to be installed.

Installation

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.

qid

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.

Generating Qual ID's

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"]}

Info

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

Contributing

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.

License

MIT