whiskers.js
This is an unofficial TypeScript-based API Wrapper for The Cat API. It allows you to easily interact with the API, providing methods to receive for cat images and breed information.
Installation
You can install the package via npm:
npm install whiskers.js
Import the client class and instantiate it with your API key:
import { Client } from "whiskers.js";
const client = new Client("your-api-key");
Methods
- getRandom
- searchImages
- getImageById
- getBreed
- getBreedList
- getCategoryList
Usage
Getting a random image
To get a random cat image or gif, use the getRandom
method.
const image = await client.getRandom();
console.log(image.url);
Search Images with a Query
To search for cat images with specific query parameters, use the searchImages
method.
Pagination requires a valid API key and has a maximum limit of 25 per page
// Retrieve the first 25 gifs
const gifs = await client.searchImages({
order: "ASC",
page: 1,
limit: 25,
mime_types: "gif"
});
gifs.data.forEach((gif) => console.log(gif.url));
The following attributes can be queried on. All are optional.
- size - The size of the images to search for. Can be 'small', 'med', or 'full'.
- mime_types - The available image types. Defaults to all types. Can be 'gif', 'jpg', 'png', or any combination of these.
- order - Order of results. Default is Random. Can be 'RANDOM', 'ASC', or 'DESC' If either ASC or DESC is passed then the Pagination headers will be on the response.
- page - The page number for results. Only used when order is ASC or DESC.
- limit - The maximum number of results to return. Default is 1. You can only pass 1 with an invalid API Key, with a valid key you can pass up to 25.
- category_ids - Comma delimited string of integers matching the id's of the Categories to filter the search. Category id's can found with getCategoryList().
- breed_ids - Comma delimited string of integers, matching the id's of the Breeds to filter the search. Breed id's can found with getBreedList().
- has_breeds - 0 or 1. Default is 0. Specifying 1 will only return images that have breed information. A valid API key is required to retrieve breed information on images.
Retrieve a cat image by its ID
To get a cat image by its ID, use the getImageById
method.
const image = await client.getImageById("image-id");
if (image) {
console.log(image.url);
}
Search for a cat breed
To search for a cat breed by its name or ID, use the getBreed
method.
const breed = await client.getBreed("Sphynx");
console.log(breed[0].description);
Partial matching is used by the API thus multiple breeds can be returned.
List all cat breeds
To get all cat breeds, use the getBreedList
method.
const breedList = await client.getBreedList();
breedList.forEach((breed) => console.log(breed.description))
Error Handling
This API wrapper throws an WhiskersError
if there is an error response from The Cat API. This error object includes useful information about what went wrong. It contains the following properties:
-
detail
: The body of the HTTP response. -
status
: The status code of the HTTP response. -
url
: The URL of the HTTP request.
Here is how you can catch and handle an WhiskersError
:
import { WhiskersError } from "whiskers.js";
try {
await client.getBreedList();
} catch (err) {
if (err instanceof WhiskersError && err.status === 429) {
console.error('Rate Limit Reached!')
}
}
Contributions
Contributions are always welcome! Please read the contribution guidelines first.
-
Fork and clone the repository: You can keep your fork synced with the upstream repository by following these instructions.
-
Create a branch: Make a branch for your changes. It's a good practice to create a new branch for each separate piece of work.
git checkout -b name-of-your-branch
-
Make your changes: Make your changes and commit them. Please make your commit messages informative.
git commit -m "commit message"
-
Run the tests: Ensure that your changes do not break any tests. If you're adding a new feature, please add tests for it.
-
Push your changes: Push your changes to your forked repository.
git push origin name-of-your-branch
-
Create a Pull Request: Go to your forked repository on GitHub and click the "New Pull Request" button. Merge to the
develop
branch. Before your Pull Request can be merged, the following conditions must be met:-
All tests must pass.
-
The change must be approved by a repository maintainer.
-
Thank you for your contributions!
License
This project is licensed under the MIT License.