docs: update usage instructions

This commit is contained in:
raf 2023-10-27 10:48:26 +03:00
parent fd3c752d66
commit 86aee3b14b
No known key found for this signature in database
GPG key ID: 02D1DD3FA08B6B29
3 changed files with 25 additions and 51 deletions

4
.gitattributes vendored Normal file
View file

@ -0,0 +1,4 @@
go.mod linguist-language=Go
go.sum linguist-language=Go
*.go linguist-language=Go
vendor/* linguist-language=Go

View file

@ -1,68 +1,39 @@
# 🐾 catApi # 🐾 catApi
> **catApi** is *scuffed* website (fully equipped with an API, obviously) to display pictures of cats from the `/images/` directory > **catApi** is a minimal, self-hostable API endpoint for serving pictures of, you guessed it, cats!
which are supplied by the kind people who sent me pictures of their cats, and also my own. More cats are always welcome in the paw zone. > but it could be used to serve anything, really
###### I was initially going to name this project "Onlypaws" but I am too lazy to implement a donation system.
## Usage
## Self-Hosting There are two ways to "use" **catApi** - you can either serve it, blessing the world with pictures of your cat
If you are, for some reason, interested in self-hosting your own version of this website; feel absolutely free to. Fork it, download it, mirror it. Not just that I *don't care* what you do with the code, I will also or be served. Below is the API documentation for visiting an existing instance of catApi.
appreciate any kind of contributions that you might decide to make. I have been told multiple times that my code is crude and scuffed, so feel free to fix that. Good luck, though.
### Dependencies ### API Documentation
* [git](https://git-scm.com/downloads)
* [NodeJS](https://nodejs.org/en/download/)
* npm or [Yarn](https://classic.yarnpkg.com/lang/en/docs/install/) (I recommend Yarn)
### With Yarn/npm **catApi** exposes several endpoints.
```sh #### ID
# Clone this git repository
git clone https://github.com/NotAShelf/catApi.git
# Move to the new directory `/api/id` will return the image with the associated ID.
cd catApi
# Install dependencies For example **`http://localhost:3000/api/id?id=3`** will return the image with the ID of "3".
yarn
# Alternatively, to install dependencies #### List
npm install
# Create the .env file for environmental variables (Optional, there are fallback options for both environmental variables) `/api/list` will return eturn a JSON object containing data about the images within the /images directory
cp .sample.env .env
# Start the application with For example, **`http://localhost:3000/api/random`** will return a JSON object that might be as follows
yarn start
# Alternatively, to start the application > `[{"id":"0","url":"/api/id?id=0"},{"id":"1","url":"/api/id?id=1"},{"id":"2","url":"/api/id?id=2"}]`
npm run start
``` #### Random
`/api/random` will return a random image from the list of available images
### Self-hosting
### With Docker Compose
TODO TODO
## Versioning
catApi is a new idea I am planning to work on (while the idea, in general, is not new, it is for me in terms of working on a project. Leave me alone.)
and thus, we are currently on the V1 branch. V2 will *probably* introduce proper FrontEnd because let's admit it, a bare website that displays
**literally a picture** and nothing else looks bad. When, you may ask? Whenever the heck I want, I answer.
## Contributing
TODO
## API Documentation (WIP)
#### `/api/id`
> return data about the specified image, by ID
> - **e.g. `http://localhost:3000/api/3`**
#### `/api/list`
> return a list of all images on the server (explicitly from the `/images` directory)
> - e.g. `http://localhost:3000/api/list`
#### `/api/random`
> returns data about a random image on the server
> - e.g `http://localhost:3000/api/random`
## License ## License
> **catApi** is licensed under the [MIT](https://github.com/NotAShelf/catApi/blob/v1/LICENSE) license. > **catApi** is licensed under the [MIT](https://github.com/NotAShelf/catApi/blob/v2/LICENSE) license.

View file

@ -1 +0,0 @@
port: 3000