Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 7816320

Browse files
mblaymanjerel
authored andcommitted
Document DJA's ability to use Compound Documents. (#308)
This branch adds documentation for how to include extra resources under the `included` key. It also adds Sphinx and the extra required dependencies to build the docs to `requirements-development.txt`.
1 parent 2dcf178 commit 7816320

File tree

2 files changed

+49
-1
lines changed

2 files changed

+49
-1
lines changed

‎docs/usage.md‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -457,8 +457,53 @@ Adding `url` to `fields` on a serializer will add a `self` link to the `links` k
457457

458458
Related links will be created automatically when using the Relationship View.
459459

460+
### Included
461+
462+
JSON API can include additional resources in a single network request.
463+
The specification refers to this feature as
464+
[Compound Documents](http://jsonapi.org/format/#document-compound-documents).
465+
Compound Documents can reduce the number of network requests
466+
which can lead to a better performing web application.
467+
To accomplish this,
468+
the specification permits a top level `included` key.
469+
The list of content within this key are the extra resources
470+
that are related to the primary resource.
471+
472+
To make a Compound Document,
473+
you need to modify your `ModelSerializer`.
474+
The two required additions are `included_resources`
475+
and `included_serializers`.
476+
477+
For example,
478+
suppose you are making an app to go on quests,
479+
and you would like to fetch your chosen knight
480+
along with the quest.
481+
You could accomplish that with:
482+
483+
```python
484+
class KnightSerializer(serializers.ModelSerializer):
485+
class Meta:
486+
model = Knight
487+
fields = ('id', 'name', 'strength', 'dexterity', 'charisma')
488+
489+
490+
class QuestSerializer(serializers.ModelSerializer):
491+
included_serializers = {
492+
'knight': KnightSerializer,
493+
}
494+
495+
class Meta:
496+
model = Quest
497+
fields = ('id', 'title', 'reward', 'knight')
498+
499+
class JSONAPIMeta:
500+
included_resources = ['knight']
501+
```
502+
503+
`included_resources` informs DJA of **what** you would like to include.
504+
`included_serializers` tells DJA **how** you want to include it.
505+
460506
<!--
461507
### Relationships
462-
### Included
463508
### Errors
464509
-->

‎requirements-development.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,8 @@ pytest>=2.9.0,<3.0
33
pytest-django
44
pytest-factoryboy
55
fake-factory
6+
recommonmark
7+
Sphinx
8+
sphinx_rtd_theme
69
tox
710
mock

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /