Confusing documentation of the citation object

[cweider]

The documentation for “Case” describes the content of citations as an “array of citation objects”. I was inclined to follow the spec under the “Citation” heading, but it does not describe what I see in the API. It’s likely that citations described refer to something else entirely – and don’t exist! A subsection for citation may need to be added to “Case” and the “Citation” section struck.

Documentation:

capstone/capstone/capweb/templates/docs/04_specs_and_reference/02_data_formats.md

Lines 48 to 59 in 821fa7b

	## Case
	{
	"id": (int),
	"url": (API url to this case),
	"name": (string),
	"name_abbreviation": (string),
	"decision_date": (string),
	"docket_number": (string),
	"first_page": (string),
	"last_page": (string),
	"citations": [array of citation objects],

capstone/capstone/capweb/templates/docs/04_specs_and_reference/02_data_formats.md

Lines 292 to 298 in 821fa7b

	## Citation
	{
	"id": (int),
	"cite": (string),
	"cited_by": (url)
	},

What an observe matches what I see in generating code of serializers.py – a dictionary with two keys: "type" and "cite".

Generating Code:

capstone/capstone/capapi/serializers.py

Line 230 in 821fa7b

{"type": c["type"], "cite": c["cite"]} for c in s["citations"]

capstone/capstone/capapi/serializers.py

Lines 55 to 58 in 821fa7b

	class CitationSerializer(serializers.ModelSerializer):
	class Meta:
	model = models.Citation
	fields = ("type", "cite")

In the documentation “Case” and “Citation” are sibling headings – could it be that “Citation” refers to a route? If it does, that route doesn’t exist anymore.

Routes:

capstone/capstone/capapi/api_urls.py

Lines 10 to 20 in 821fa7b

	router = routers.DefaultRouter()
	router.register('cases', api_views.CaseDocumentViewSet, basename="cases")
	router.register('jurisdictions', api_views.JurisdictionViewSet)
	router.register('courts', api_views.CourtViewSet)
	router.register('volumes', api_views.VolumeViewSet)
	router.register('reporters', api_views.ReporterViewSet)
	router.register('bulk', api_views.CaseExportViewSet)
	router.register('ngrams', api_views.NgramViewSet, basename='ngrams')
	router.register('user_history', api_views.UserHistoryViewSet)
	router.register('resolve', api_views.ResolveDocumentViewSet, basename="resolve")