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
-
-
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 basicDockerfile
,docker-compose.yml
file, 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)
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.8.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4d6bab52df21d520026751242bccafec5758d1840b750d63a69bf81cf239937b |
|
MD5 | 87d600a6dc6474cc053f3659c0de43dd |
|
BLAKE2b-256 | 66c41b23aa018bf0836ef4a77ee5473db2382200f091702103a9850dd1b3cd7a |