https://github.com/haukurk/flask-restapi-recipe
A recipe for a RESTful API with key authentication. Powered with Flask+SQLALchemy and a minimal amount of external dependencies.
https://github.com/haukurk/flask-restapi-recipe
Last synced: 3 months ago
JSON representation
A recipe for a RESTful API with key authentication. Powered with Flask+SQLALchemy and a minimal amount of external dependencies.
- Host: GitHub
- URL: https://github.com/haukurk/flask-restapi-recipe
- Owner: haukurk
- License: mit
- Created: 2014-07-09T13:29:27.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2020-09-02T09:55:59.000Z (over 4 years ago)
- Last Synced: 2024-08-13T07:08:51.741Z (6 months ago)
- Language: Python
- Homepage:
- Size: 30.3 KB
- Stars: 60
- Watchers: 6
- Forks: 23
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - haukurk/flask-restapi-recipe - A recipe for a RESTful API with key authentication. Powered with Flask+SQLALchemy and a minimal amount of external dependencies. (Python)
README
[](https://travis-ci.org/haukurk/flask-restapi-recipe)
[N.b. The API authentication approach is quite outdated. Please look into other ways such as JWT tokens]
# A simple recipe for a RESTful API packaged with an API key authentication.
This recipe is a really simple seed for a RESTful API, powered by Flask and SQLALchemy.
It's a perfect starting point if you are in need of an API, quickly... At least I think so!
The recipe includes the following features:
* A naive method of API versioning.
* Ability to switch between a development and Default application config, by using environmental variables.
* Simple test cases in a form of unit tests.
* Authentication component which you can decorate API methods with.
* Manage.py, manages keys and allowed IPs (where 0.0.0.0 is considered all IPs).
* The decorator *@require_app_key*, from *restapi.components.auth.decorators* then only allows keys generated with manage.py
* API control, run.py:
* *-r* runs a development server
* *-i* initializes the database based on imported SQLALchemy models
* *-z* creates a interactive console, with flask app imported.
# Quick Start
Use virtual environment, please.
```
$> pip install virtualenv
$> virtualenv venv/
```
Activate environment.
```
$> . venv/bin/active
```
Install requirements for the project
```
$> pip install -r requirements.txt
```
Init the default SQLite database:
```
$> python run.py -i
```
Run the development server
```
$> python run.py -r
```
# Create you first API key
Generate an key for localhost (127.0.0.1)
```
$> python manage.py -g 127.0.0.1 "localhost Development Key"
```
You should get an output like:
```
Issued a key 'eMtUDd3ZF19M9Dk7fOgSKmpuqX0KV6sHDwfrydiN0gk' for the IP '127.0.0.1' (localhost development key) with KEY ID: 2.
```
Next, try to insert a cake object to the database (it's authentication protected by default) by using *curl*:
```
$> curl -X POST -d "cakename=Test Cake&baker=Haukur Kristinsson&price=200" http://localhost:5000/api/v1.1/cakes/?key=eMtUDd3ZF19M9Dk7fOgSKmpuqX0KV6sHDwfrydiN0gk
```
You should get an status=success (Remember JSEND standard) output:
```
{
"data": {
"cakes": {
"bakername": "Haukur Kristinsson",
"cakename": "Test Cake",
"id": 6,
"price": 200.0,
"price_range": "expensive"
}
},
"status": "success"
}
```
# Authentication Method
Authentication for this API is handled by a classic "API key" methodology which allows the client to pass the key as an URL parameter *key* (i.e. http://api/?key=KEY).
Nothing fancy about that... But its should be noted that this method is only secure while using encrypted channels between clients and the web server.
When issuing a API key, you can either specify a IP address that is to be allowed when using the key, or by using the IP 0.0.0.0 to allow all IP addresses.
Summary of manage.py (authentication manager):
* To generate a API key you use
```
./run.py -g IP -c "this IP is for the engineer on floor 3" (If you define IP as 0.0.0.0 you are allowing the API key to be used from any remote IP)
```
* To remove a API key you use
```
./run -d APIKEYID (APIKEYIDs are shown when running run.py with the -a flag)
```
* To show all issued keys use
```
./run -a
```
# Testing
To run unittest classes simply run them with nose:
```
nosetests -v tests/unittest_basics.py
```
# JSON responses
I advise to keep responses formats under control and to stay consistent at all times.
You could follow the JSend specification (http://labs.omniti.com/labs/jsend), or at least base you output format from there.
# Example API methods
I included 2 API methods, just as an example of how you can use it:
* cakes modules (/api/v/weather)
I'm not going to into detail of each one, you should just look at the source code.