{
"info": {
"author": "Bipin Suresh",
"author_email": "bipins@alumni.stanford.edu",
"bugtrack_url": null,
"classifiers": [
"Environment :: Web Environment",
"Framework :: Django",
"Intended Audience :: Developers",
"License :: OSI Approved :: BSD License",
"Operating System :: OS Independent",
"Programming Language :: Python",
"Topic :: Internet :: WWW/HTTP",
"Topic :: Internet :: WWW/HTTP :: Dynamic Content"
],
"description": "=================\nDjango API\n=================\n\n``django_api`` lets you specify and validate your Django_ APIs in a single block of code.\n\nIt does this with an ``@api`` decorator that wraps Django views. This keeps the API documentation consistent, localized and declarative.\n\n::\n\n from django import forms\n from django_api.decorators import api\n from django_api.json_helpers import JsonResponse\n from django_api.json_helpers import JsonResponseForbidden\n\n\n @api({\n 'accepts': {\n 'x': forms.IntegerField(min_value=0),\n 'y': forms.IntegerField(max_value=10),\n },\n 'returns': {\n 200: 'Addition successful',\n }\n })\n def add(request, *args, **kwargs):\n # `x` and `y` have been validated, and are integers\n # so we can safely perform arithmetic operations on them\n return JsonResponse({\n 'sum': request.GET['x'] + request.GET['y']\n })\n\n\n.. _Django: https://www.djangoproject.com/\n\nBased on the above example, the following API responses are automatically available (assuming you wire up the ``/add`` route to the view above:\n\n::\n\n GET /add\n\n \"failed to validate: {'y': [u'This field is required.'], 'x': [u'This field is required.']}\"\n\n\n GET /add?x=10\n\n \"failed to validate: {'y': [u'This field is required.']}\"\n\n\n GET /add?x=10&y=100\n\n \"failed to validate: {'y': [u'Ensure this value is less than or equal to 10.']}\"\n\n\n GET /add?x=10&y=10\n\n {sum: 20}\n\n\n------------\nDependencies\n------------\n\nNone\n\n------------\nInstallation\n------------\n\nTo use ``django_api`` in your Django project it needs to be accessible by your \nPython installation::\n\n\t$ pip install django-api\n\n(or simply place the ``django_api`` directory in your $PYTHON_PATH)\n\n------------\nDjango Setup\n------------\n\nAdd ``django_api`` to ``INSTALLED_APPS`` in your project's ``settings.py``.\n\nExample::\n\n\tINSTALLED_APPS = (\n\t\t'django.contrib.auth',\n\t\t'django.contrib.contenttypes',\n\t\t'django.contrib.sessions',\n\t\t'django.contrib.sites',\n\t\t'django.contrib.admin',\n\t\t'django_api',\n\t)\n\n\n-----\nUsage\n-----\n\nSpecify your API by using the ``@api`` decorator. The ``@api`` decorator takes a dictionary with two keys: ``accepts`` and ``returns``.\n\n::\n\n from django_api.decorators import api\n @api({\n 'accepts': {\n },\n 'returns': {\n }\n })\n def add(request, *args, **kwargs):\n\n\naccepts\n-------\n\nDescribe the query parameters your API accepts by listing them out in the ``accepts`` dictionary. Each entry in the ``accepts`` section\nmaps a name to a `Django form field\n`_ type.\nReceived query parameters are automatically converted to the specified type. If the parameter does not conform to the specification\nthe query fails to validate (see below).\nOnce validated, the variables will be placed in the ``request`` dictionary for use within the view.\n\n\n::\n\n 'accepts': {\n 'x': forms.IntegerField(min_value=0),\n 'y': forms.IntegerField(max_value=10, required=False),\n 'u': User(),\n }\n \nSince each parameter is specified using a Django form field, any argument that its class constructor takes can be used. Examples include \n\n* ``required``\n* ``initial``\n* ``max_length`` for ``CharField``\n* ``min_value`` for ``IntegerField``\n\nFor a full reference, please `see here `_.\n\nreturns\n-------\n\nBy default, the ``@api`` decorator checks that the returned response is of JSON type.\n\nSpecify the valid returned HTTP codes by listing them out in the ``returns`` dictionary.\nEach entry in the dictionary maps a HTTP response code to a helpful message, explaining the outcome\nof the action. The helpful message is for documentation purposes only.\nIf the response does not conform to the specification, the query will fail to validate (see below).\n\n::\n\n 'returns': {\n 200: 'Addition successful',\n 403: 'User does not have permission',\n 404: 'Resource not found',\n 404: 'User not found',\n }\n\n\nValidation\n----------\nIf validation fails, a ``HTTP 400 - Bad request`` is returned to the client. For safety, ``django_api`` will perform validation only if ``settings.DEBUG = True``.\nThis ensures that production code always remains unaffected. \n\n\nTesting\n----------\nRun the tests with the folllowing command\n\n::\n\n python manage.py test django_api\n\n\n--------------\nAdvanced usage\n--------------\n\nDjango Models\n--------------\n\n``@accepts`` can be used to also accept your Django models through the object's ``id``. For a Model ``Model``, Django expects the query parameter to be name ``model-id``.\n\n::\n\n 'accepts': {\n 'x': forms.IntegerField(min_value=0),\n 'y': forms.IntegerField(max_value=10, required=False),\n 'u': User(),\n }\n\nYou can also simply choose to validate either only the parameters the\nAPI accepts, or the return values of the API.\n\nExample::\n\n\n from django import forms\n from django_api.decorators import api_accepts\n from django_api.json_helpers import JsonResponse\n from django_api.json_helpers import JsonResponseForbidden\n\n\n @api_accepts({\n 'x': forms.IntegerField(min_value=0),\n 'y': forms.IntegerField(min_value=0),\n })\n def add(request, *args, **kwargs):\n return JsonResponse({\n 'sum': request.GET['x'] + request.GET['y']\n })\n\n\n\n\n from django import forms\n from django_api.decorators import api_returns\n from django_api.json_helpers import JsonResponse\n from django_api.json_helpers import JsonResponseForbidden\n\n\n @api_returns({\n 200: 'Operation successful',\n 403: 'User does not have permission',\n 404: 'Resource not found',\n 404: 'User not found',\n })\n def add(request, *args, **kwargs):\n return JsonResponse({\n 'sum': request.GET['x'] + request.GET['y']\n })",
"description_content_type": null,
"docs_url": null,
"download_url": null,
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/bipsandbytes/django-api",
"keywords": null,
"license": "BSD License",
"maintainer": null,
"maintainer_email": null,
"name": "django-api",
"package_url": "https://pypi.org/project/django-api/",
"platform": "UNKNOWN",
"project_url": "https://pypi.org/project/django-api/",
"project_urls": {
"Homepage": "https://github.com/bipsandbytes/django-api"
},
"release_url": "https://pypi.org/project/django-api/0.1.3/",
"requires_dist": null,
"requires_python": null,
"summary": "Specify and validate your Django APIs",
"version": "0.1.3"
},
"last_serial": 1461510,
"releases": {
"0.1": [
{
"comment_text": "",
"digests": {
"md5": "a7cdcf7a61de441ac9d727e3512f4c98",
"sha256": "606e54848be1f48166b12bae36501bbc8d2e3b2b23e63fb97c2a3392bf08558e"
},
"downloads": -1,
"filename": "django-api-0.1.tar.gz",
"has_sig": false,
"md5_digest": "a7cdcf7a61de441ac9d727e3512f4c98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7837,
"upload_time": "2015-03-09T22:19:08",
"url": "https://files.pythonhosted.org/packages/de/ff/c54cc69070ab14738bbeb42c7d7a9a801c619ea577d568b2b4dd24abe4f3/django-api-0.1.tar.gz"
}
],
"0.1.1": [
{
"comment_text": "",
"digests": {
"md5": "0647e6dcbc5bcc5ab67c963b9b41578a",
"sha256": "287d44d636628d257480095288acfedc13a77ab0be59197d3f11cfa60cc33838"
},
"downloads": -1,
"filename": "django-api-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "0647e6dcbc5bcc5ab67c963b9b41578a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7921,
"upload_time": "2015-03-09T23:26:49",
"url": "https://files.pythonhosted.org/packages/20/31/b4fd503d0fb605cef4f883e61510afde37b383466af71b65ee5a43e7db6f/django-api-0.1.1.tar.gz"
}
],
"0.1.2": [
{
"comment_text": "",
"digests": {
"md5": "0c024a6dd9458a6944c2b3c8e75aa5f5",
"sha256": "954bef60cb325769d284a4f614a4edd125b3fbfab5c7839efd06881a2518aaac"
},
"downloads": -1,
"filename": "django-api-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "0c024a6dd9458a6944c2b3c8e75aa5f5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8243,
"upload_time": "2015-03-11T23:08:59",
"url": "https://files.pythonhosted.org/packages/8a/7b/23564d5a4dbf5d193cc766f69a0801d8efde356652c3acdfba5c08f67c49/django-api-0.1.2.tar.gz"
}
],
"0.1.3": [
{
"comment_text": "",
"digests": {
"md5": "4d4c805b4a298ede91aba0777f524dcc",
"sha256": "542a627f217f8726c0ea290c805b30cd08464d18d33a005130b55ae485345ced"
},
"downloads": -1,
"filename": "django-api-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "4d4c805b4a298ede91aba0777f524dcc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8512,
"upload_time": "2015-03-15T08:45:37",
"url": "https://files.pythonhosted.org/packages/82/83/ac45b979b40f4fea85ab16c93733d0c2513749dab963f42dad02263646d2/django-api-0.1.3.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "4d4c805b4a298ede91aba0777f524dcc",
"sha256": "542a627f217f8726c0ea290c805b30cd08464d18d33a005130b55ae485345ced"
},
"downloads": -1,
"filename": "django-api-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "4d4c805b4a298ede91aba0777f524dcc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 8512,
"upload_time": "2015-03-15T08:45:37",
"url": "https://files.pythonhosted.org/packages/82/83/ac45b979b40f4fea85ab16c93733d0c2513749dab963f42dad02263646d2/django-api-0.1.3.tar.gz"
}
]
}