Getting started
===============

To install Podiant API, simply run::

    pip install podiant-api

Then add the app to your settings::

    INSTALLED_APPS = (
        ...
        'api',
        ...
    )

There are no models, and the package does not come with its own URLconf.

Quickstart
----------

The quickest way to create an API endpoint for a model is to use the
:doc:`REST shortcut <../api/rest>`.

Let's say our app's `models.py` file looks like this::

    from django.db import models

    class List(models.Model):
        name = models.CharField(max_length=255)
        creator = models.ForeignKey(
            'auth.User',
            related_name='lists',
            on_delete=models.CASCADE
        )

    class Task(models.Model):
        list = models.ForeignKey(
            List,
            related_name='tasks',
            on_delete=models.CASCADE
        )

        name = models.CharField(max_length=255)
        completed = models.BooleanField(default=False)

We would add the following to our app's `urls.py` file::

    from api.urls import rest
    from django.contrib.auth.models import User
    from .models import List, Task

    urlpatterns = rest(
        List,
        fields=('name',),
        readonly_fields=('creator',),
        prepopulated_fields={
            'creator': lambda request: request.user
        },
        relations=(
            'creator',
            'tasks'
        )
    ) + rest(
        Task,
        fields=(
            'name',
            'completed'
        ),
        relations=(
            'creator',
            'list'
        )
    ) + rest(
        User,
        exclude=(
            'email',
            'password',
            'is_superuser',
            'is_staff',
            'groups',
            'user_permissions'
        ),
        readonly_fields=(
            'date_joined',
            'last_login'
        ),
        order_by=('last_name', 'first_name'),
        relations={
            'lists',
        }
    )

    app_name = 'todos'

We now include our app's URLconf in our project, like so::

    from django.conf.urls import url, include
    from .todos import urls as todos_urls

    urlpatterns = [
        url(r'^api/', include(todos_urls, 'api'))
    ]

We make sure to include the namespace argument. It must be set to 'api', and
in Django>=2.0, the app's URLconf must contain an `app_name` attribute.

This should expose the following URLs::

    /api/lists/
    /api/lists/<list_id>/
    /api/lists/<list_id>/tasks/
    /api/lists/<list_id>/relationships/tasks/
    /api/lists/<list_id>/creator/
    /api/lists/<list_id>/relationships/creator/

    /api/tasks/
    /api/tasks/<task_id>/
    /api/lists/<list_id>/lists/
    /api/lists/<list_id>/relationships/lists/

    /api/users/
    /api/users/<username>/
    /api/users/<username>/lists/
    /api/users/<username>/relationships/lists/

The ``/api/users/<username>/`` URLs are a special case, as it uses the
:ref:`API_URL_OVERRIDES setting <settings.API_URL_OVERRIDES>`
setting so that the username is used to identify the user instead of the primary
key.

JSON API
--------

Podiant API is built to allow the easy creation of JSON-API-compliant endpoints.
For more information, see the
`JSON API documentation <http://jsonapi.org>`_.