stares-api 0.2.0.dev6
REST API to serve static JSON files
License: MIT
Requires Python: >=3.8
Keywords: api rest json static resources rapid development

# Stares API


Stares API is a lightweight service with the intent to rapidly prototype APIs and
to easily serve static content via a RESTful service.
It is based on [CherryPy](https://cherrypy.org), one of the fastest WSGI 
frameworks written in Python ([source](https://www.appdynamics.com/blog/engineering/a-performance-analysis-of-python-wsgi-servers-part-2/)).



## Features

Walks through a folder structure and provides each JSON file as a RESTful service.
The root element of the JSON file has to be an array.

Allowed query params per resource is the number of requestes elements `n`.
By default it serves one element.
In case you want to query all elements, just query the resource with `n = all`.

If you query more elements than the array consists of, then it repeats the entries.

Another query param is the `shuffle` parameter. Set it to `true` or `1` in order to query a random sample of the array list.
Again, if you combine it with `n` and `n > resource.length` then repitition will occur.

Each object, that is served, contains a key-value pair called `__hash`.
The `__hash` value is a uniquely assigned hash to each object, that is served.
This is useful, if you insist on excluding specific elements from the JSON file.


## Examples

The service is locally served on port `8080`.
The API base URL has the value `/api/v1`.


```
# query the first element of the sample resource "ipsum.json"
curl http://localhost:8080/api/v1/ipsum

# query the first 3 elements
curl http://localhost:8080/api/v1/ipsum?n=3

# query all elements
curl http://localhost:8080/api/v1/ipsum?n=all

# query a random element:
curl http://localhost:8080/api/v1/ipsum?shuffle=true
curl http://localhost:8080/api/v1/ipsum?shuffle=1

# query 3 random elements:
curl http://localhost:8080/api/v1/ipsum?n=3&shuffle=true

# query all elements in a random order
curl http://localhost:8080/api/v1/ipsum?n=all&shuffle=true

```



## Setup

At the moment, Stares API is not available at PyPI. I will try to add it soon.


Currently, the only way to host it is to clone the repository.
In the root folder of the repository (not the sources folder), execute the 
`stares.py` file.

```
# Directory: ./
src/stares.py [options]
```

By default, Stares API will look for a directory called `resources`.
The directory will be created, if it does not exist.
However, hot-reloading is not implemented yet.


## Configuration

TODO


## Hosting directory: /var/www/api

By default, the service looks for files in the folder `/var/www/api`.
The subfolder `resources` includes the default resource files, unless otherwise specified.
The subfolder `public` can contain publicly served files.
The index file should be called `index.html`.


## TODO: 

- [ ] Create a Pip package and provide it via pip
- [ ] Nested repositories, when walking through the folder structure
- [ ] Hotreloading of the resource directory
- [ ] Exception handling to increase UX
- [x] Docs page to describe the API resources
- [ ] Custom logger to increase UX
- [ ] Configurable root directory with static files to be served






# License

MIT License

Copyright (c) 2020 stares-api

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.