Metadata-Version: 1.1
Name: tg-apicore
Version: 0.3.0
Summary: Opinionated API framework on top of Django REST framework
Home-page: https://github.com/thorgate/tg-apicore
Author: Thorgate
Author-email: code@thorgate.eu
License: ISC license
Description: =================
        Thorgate API Core
        =================
        
        
        .. image:: https://img.shields.io/pypi/v/tg-apicore.svg
                :target: https://pypi.python.org/pypi/tg-apicore
        
        .. image:: https://img.shields.io/travis/thorgate/tg-apicore.svg
                :target: https://travis-ci.org/thorgate/tg-apicore
        
        .. image:: https://readthedocs.org/projects/tg-apicore/badge/?version=latest
                :target: https://tg-apicore.readthedocs.io/en/latest/?badge=latest
                :alt: Documentation Status
        
        
        Opinionated API framework on top of Django REST framework
        
        
        * Free software: ISC license
        
        Supports Python 3.5+, Django 1.11+, Django REST framework 3.6+
        
        
        Features
        --------
        
        * API documentation automatically generated from your views
            * General intro can be added
            * You can add example request/response data
            * Autogenerated Python `requests`-based examples
            * Not interactive yet
        * Integrates `JSON API <http://jsonapi.org/>`_
            * Cursor pagination with configurable page size
        * Viewset classes for using different serializers and querysets for list/detail/edit endpoints
        * API-specific 404 view
        * Test utilities, e.g. for response validation
        * Versioning (WIP)
            * Transformer-based approach, inspired by
              `djangorestframework-version-transforms <https://github.com/mrhwick/django-rest-framework-version-transforms>`_
              and `Stripe <https://stripe.com/blog/api-versioning>`_
        
        
        Usage
        -----
        
        - ``pip install tg-apicore``
        - Add ``tg_apicore`` to ``INSTALLED_APPS``
        - Ensure your ``REST_FRAMEWORK`` setting contains ``ALLOWED_VERSIONS``, e.g:
        
          .. code:: python
        
              # In your Django project settings:
              REST_FRAMEWORK = {
                  'ALLOWED_VERSIONS': ('2018-01-01',),
              }
        
        - Note that the default paginator requires that your models have ``created`` field
        
        - Create API documentation view by subclassing ``APIDocumentationView`` and making necessary modifications.
          See ``example/example/views.py`` for example.
        - Add main API urls plus 404 view (as fallback).
        
        
        Here's an example ``urls.py``:
        
        .. code:: python
        
            from tg_apicore.views import PageNotFoundView
        
            from myproject.views import MyProjectAPIDocumentationView
        
            urlpatterns = [
                # The documentation view
                url(r'^api-docs/', MyProjectAPIDocumentationView.as_view(), name='api-docs'),
        
                # myproject.urls_api should contain your API urls patterns
                url(r'^api/(?P<version>(\d{4}-\d{2}-\d{2}))/', include('myproject.urls_api')),
        
                # API-specific 404 for everything under api/ prefix
                url(r'^api/', include(PageNotFoundView.urlpatterns())),
            ]
        
        See ``example`` directory for a more in-depth demo.
        
        
        Credits
        -------
        
        This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
        
        .. _Cookiecutter: https://github.com/audreyr/cookiecutter
        .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
        
        
        =======
        History
        =======
        
        0.3.0 (2018-05-23)
        ------------------
        
        * Add Usage section to README (to make starting up easier)
        * Most ``REST_FRAMEWORK`` settings are now automatically configured by Thorgate API Core.
          Users only need to specify ``ALLOWED_VERSIONS``, the rest is optional.
        
        
        0.2.1 (2018-04-14)
        ------------------
        
        * Fix packaging (tg_apicore subdirs weren't included)
        
        
        0.2.0 (2018-04-14)
        ------------------
        
        * Added PageNotFoundView (JSON-based 404 views)
        * Added DetailSerializerViewSet (different serializers and queryset for list/detail/edit views)
        * Added CreateOnlyFieldsSerializerMixin, ModelValidationSerializerMixin and BaseModelSerializer
        * Renamed APIDocumentationView.get_patterns() to .urlpatterns()
        * Improved example app a lot. It now also includes tests that partially test tg-apicore itself
        
        
        0.1.0 (2018-03-08)
        ------------------
        
        * First release on PyPI.
        
Keywords: tg-apicore django djangorestframework
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
