Templates and scripts to rapidly spin up a production-ready Eve-based API.
Project description
eve-utils
Templates and scripts to rapidly spin up a production-ready Eve-based API.
Please note: although I currently use these tools to create production-ready APIs, the tools themselves are still under development. Use at your own risk.
Introduction
Eve is amazing. The full power of Flask/Python, optimized for an API over mongodb. Nice.
It does take a bit of work to go from the simple example in the docs...
settings = {'DOMAIN': {'people': {}}}
app = Eve(settings=settings)
app.run()
...to a production-ready API, with robust exception handling, logging, control endpoints, configurability, (and so much more).
eve-utils helps make some of that work easier.
Install eve-utils with pip.
pip install eve-utils
Getting Started
Get started with three easy steps
-
Create your API (I recommend creating a virtual environment first)
mkapi my-api --with_docker
(note: if you don't have docker installed, create the API without
--with-docker
, then later run the API withpython run.py
- assuming you have mongodb running on localhost:27127) -
Add domain resources
cd my-api mkresource people
-
Build and launch the API
cd .. image-build docker-compose up -d
(note:
image-build
is usually called with a version number so the new docker image is correctly tagged - see more in the docs below)
Try it out with the following curl commands (or use Postman if you prefer)
curl http://localhost:2112
curl http://localhost:2112/_settings
curl -X POST http://localhost:2112/people -H "Content-type: application/json" -d "{\"name\":\"Michael\"}"
curl http://localhost:2112/people
If you followed the above, be sure to clean up after playing around with your new API:
docker-compose down
docker image rm my-api
Commands
-
mkapi
-
creates folder named api-name
-
creates a skeleton Eve API in that folder
-
for more details run
mkapi -h
-
-
mkresource
-
adds resource-name to the domain
-
default fields are name, description
-
add fields by modifying domain/resource-name.py - as you would any Eve resource
-
NOTE: resources in Eve are collections, so eve-utils names resources as plural by convention,
-
i.e. if you enter mkresource dog it will create an endpoint named /dogs
-
eve-utils rely on the inflect library for pluralization, which is very accurate but can make mistakes
-
-
-
mkrel
-
For example:
mkresource person mkresource cars mkrel person car
- you could also have typed
mkrel people cars
ormkrel person cars
- they all are equivalent
- you could also have typed
-
If you followed the example above, you have already POSTed a person named Michael:
curl -X POST http://localhost:2112/people -H "Content-type: application/json" -d "{\"name\":\"Michael\"}"
-
Normally GET a person by
_id
. eve-utils wires up the name field as anadditonal_lookup
, so you can also GET by name.curl http://localhost:2112/people/Michael?pretty
{ "_id": "606f5453b43a8f480a1b8fc6", "name": "Michael", "_updated": "2021-04-08T19:06:59", "_created": "2021-04-08T19:06:59", "_etag": "6e91d500cbb0a2f6645d9b4dced422d429a69820", "_links": { "self": { "href": "/people/606f5453b43a8f480a1b8fc6", "title": "person" }, "parent": { "title": "home", "href": "/" }, "collection": { "title": "people", "href": "people" }, "cars": { "href": "/people/606f5453b43a8f480a1b8fc6/cars", "title": "cars" } } }
-
Notice the
_links
field includes a rel namedcars
. You can POST a car to thathref
(I'll demonstrate with Javascript):const axios = require('axios') axios.defaults.baseURL = 'http://localhost:2112' axios.get('/people/Michael').then((response) => { const person = response.data const car = { name: 'Mustang' } axios.post(person._links.cars.href, car) })
-
-p
--as_parent_ref
: field name defaults to_
parent-resource_ref
, e.g. if the parent name was dogs the field would be_dog_ref
. Using this parameter, the field name become literally_parent_ref
. Useful to implement generic parent traversals.
-
-
add_docker
- run this in the folder above the root api folder to create a basic docker files and some useful build scripts (to be further documented later).-
NOTE: not necessary if you have created the API using
--with_docker
-
Adds the following files:
Dockerfile
docker-compose.yml
(note: by default this file does not use a volume for mongodb, so killing the container also kills your data).docker-ignore
image-build
image-build.bat
-
-
add_auth
- run this in the API folder. It will add a folder namedauth
with modules to add authorization to your API (docs to come) -
add_val
- run this in the API folder. It will add a folder namedvalidation
with a module that adds custom validator toEveService
. Use this to extend custom validations. It comes with two:-
NOTE: not necessary if you have created the API using
--with_val
-
unique_ignorecase
- works exactly like the built-inunique
validator except case is ignored -
unique_to_parent
- set this to a string of a resource's parent (singular!). Uniqueness will only be applied to sibling resources, i.e. the same name can be used if the resource has a different parent.-
e.g.
mkresource region mkresource store mkrel region store
Now in domain.store, change the name field definition from this:
'name": { 'type': 'string', ... 'unique': True }
to this:
'name": { 'type': 'string', ... 'unique_to_parent': 'region' }
-
-
MORE TO COME!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for eve_utils-0.9.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9077b5cb3a751b708795e6066969002d786490d84e95bba7f4ada34fe7653ca6 |
|
MD5 | e1c863b542a7323a11bb8797e2b75264 |
|
BLAKE2b-256 | 438343019ab8e82cde3938aaaf1f9068a5a77036d5a1b7497c17fcd3e3a8026f |