API

We use django REST Framework to enable API routing. Here below the basic configuration for REST as decribed in miller/settings.py

# settings.py

REST_FRAMEWORK = {
    # Use Django's standard `django.contrib.auth` permissions,
    # or allow read-only access for unauthenticated users.
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticatedOrReadOnly',
    ),
    'DEFAULT_RENDERER_CLASSES': (
        'rest_framework.renderers.JSONRenderer',
    ),
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 4
}

The API viewsets are located in their relative model filename miller/api/<model>.py: e.g. api.StoryViewSet is located at miller/api/story.py and dispatches Story model. Two kind of serializers per model are available. All serializers are coded in the same script miller/api/serializers.py. For each module, there are two versions min: a complete version for single instance retrieve or update, and a lite version, used in lists.

The routing is served in urls.py using the default rest_framework.routers module:

router.register(r'user', api.UserViewSet)
router.register(r'collection', api.CollectionViewSet)
router.register(r'story', api.StoryViewSet)
router.register(r'caption', api.CaptionViewSet)
router.register(r'document', api.DocumentViewSet)
router.register(r'mention', api.MentionViewSet)
router.register(r'profile', api.ProfileViewSet)
router.register(r'tag', api.TagViewSet)
router.register(r'comment', api.CommentViewSet)
router.register(r'author', api.AuthorViewSet)
router.register(r'review', api.ReviewViewSet)
router.register(r'pulse', api.PulseViewSet)
router.register(r'page', api.PageViewSet)

endpoints

As in the , all the REST routers are served under /api/ and follow the rest_framework.routers rules for Viewsets. Some exceptions applies according to user authentification: if you're not authentified and you point your browser to http://localhost:8000/api/story/ (or whatever host are you using) the REST gives you back the list of PUBLIC stories. If you're authentified, the same REST ives you back the list of PUBLIC stories PLUS the list of the stories you authored.

simple example

Calling the api http://localhost:8000/api/story/ via GET returns this list of story instances (you can specify the limit and offset params as wished - note that this may affect response time):

{
  "count":87,
  "next":"http://localhost:8000/api/story/?limit=4&offset=4",
  "previous":null,
  "results":[
    {
      "id":91,
      "slug":"bonobostudio-the-sleepwalker",
      "short_url":"D8amDA5",
      "date":"2017-01-05T13:58:55.777448Z",
      "date_created":"2017-01-05T13:58:55.777413Z",
      "date_last_modified":"2017-01-20T13:23:17.068034Z",
      "status":"public",
      "covers":[],
      // ...
    },
  // ...
  ]
}

Please cfr. the serializer class to get more details about the expected fields shipped with each API endpoint.

filtering and sorting

Filtering and sorting is avaialbe only for a few models and follows the django queryset evaluation.

sorting: order_by via ordering http param

To sort lists by specific properties, we use the default django order_by params.

That is, calling http://localhost:8000/api/story/?ordering=-date_creted,-pk is mapped directly to:

<queryset>.order_by('-date_creted', '-pk')

If properties do not exist, the default ordering is then applied.