django-formapi
Create JSON API:s with HMAC authentication and Django form-validation.
Version compatibility
See Travis-CI page for actual test results: https://travis-ci.org/5monkeys/django-formapi
| Django | Python 2.6 | 2.7 | 3.3 | 3.4 | 3.5 | 3.6 |
|---|---|---|---|---|---|---|
| 1.3 | Yes | Yes | ||||
| 1.4 | Yes | Yes | ||||
| 1.5 | Yes | Yes | Yes | |||
| 1.6 | Yes | Yes | Yes | |||
| 1.7 | Yes | Yes | Yes | |||
| 1.8 | Yes | Yes | Yes | Yes | Yes | |
| 1.9 | Yes | Yes | Yes | Yes | ||
| 1.10 | Yes | Yes | Yes | Yes |
Installation
Install django-formapi in your python environment
$ pip install django-formapi
Add formapi to your INSTALLED_APPS setting.
INSTALLED_APPS = (
...
'formapi',
)
Add formapi.urls to your urls.py.
urlpatterns = patterns('',
...
url(r'^api/', include('formapi.urls')),
)
Usage
Go ahead and create a calls.py.
class DivisionCall(calls.APICall):
"""
Returns the quotient of two integers
"""
dividend = forms.FloatField()
divisor = forms.FloatField()
def action(self, test):
dividend = self.cleaned_data.get('dividend')
divisor = self.cleaned_data.get('divisor')
return dividend / divisor
API.register(DivisionCall, 'math', 'divide', version='v1.0.0')
Just create a class like your regular Django Forms but inheriting from APICall. Define the fields that your API-call should receive. The action method is called when your fields have been validated and what is returned will be JSON-encoded as a response to the API-caller. The API.register call takes your APICall-class as first argument, the second argument is the namespace the API-call should reside in, the third argument is the name of your call and the fourth the version. This will result in an url in the form of api/[version]/[namespace]/[call_name]/ so we would get /api/v1.0.0/math/divide/.
A valid call with the parameters {'dividend': 5, 'divisor': 2} would result in this response:
{"errors": {}, "data": 5, "success": true}
An invalid call with the parameters {'dividend': "five", 'divisor': 2} would result in this response:
{"errors": {"dividend": ["Enter a number."]}, "data": false, "success": false}
Authentication
By default APICalls have HMAC-authentication turned on. Disable it by setting signed_requests = False on your APICall.
If not disabled users of the API will have to sign their calls. To do this they need a secret generate, create a APIKey through the django admin interface. On save a personal secret and key will be generated for the API-user.
To build a call signature for the DivisonCall create a querystring of the calls parameters sorted by the keys dividend=5&divisor=2. Create a HMAC using SHA1 hash function. Example in python:
import hmac
from hashlib import sha1
hmac_sign = hmac.new(secret, urllib2.quote('dividend=5&divisor=2'), sha1).hexdigest()
A signed request against DivisionCall would have the parameters {'dividend': 5, 'divisor': 2, 'key': generated_key, 'sign': hmac_sign}
Documentation
Visit /api/discover for a brief documentation of the registered API-calls.
980 Jan 06, 2023
5 Nov 29, 2021
165 Jan 08, 2023
139 Dec 05, 2022
10 Jan 04, 2023
5 May 06, 2022
167 Oct 18, 2022
1 Oct 29, 2021
113 Jan 04, 2023
31 Aug 09, 2022
1 Feb 22, 2022
12 Jan 21, 2020
5 Nov 15, 2022
2 Sep 08, 2022
1 Jan 31, 2022
53 Jan 05, 2023
8 Jun 25, 2021
1.2k Jan 05, 2023
980 Dec 29, 2022
1 Sep 28, 2021