Example app name conflicts

[ThibaultLemaire]

In Running the example app in the docs, there is the command

django-admin.py startproject example .

But that creates a new django project named 'example' in the current directory, which is rejected by the OS because there already is an 'example' directory.

I haven't had the time to investigate any further, but either you want to name the new project differently (but then what's the point of creating an empty django project? This doesn't show how to use DJA at all), or you want to use another command than startproject.

[n2ygk]

Agreed this is incorrectly documented. When I first tried using this package, the example documentation was out of date and I tried my best to improve it given my limited knowledge (#410, #411 ). I've learned a lot more since then thanks to @sliverc, @mblayman and others.

Try this and please report back if this works for you:

git clone https://github.com/django-json-api/django-rest-framework-json-api.git
cd django-rest-framework-json-api
python3 -m venv env
source env/bin/activate
pip install -r example/requirements.txt
pip install -e .
django-admin migrate --settings=example.settings
django-admin runserver --settings=example.settings

You should then be able to use Postman, for example, to GET http://127.0.0.1:8000/ which will return this:

{
    "data": {
        "blogs": "http://127.0.0.1:8000/blogs",
        "entries": "http://127.0.0.1:8000/entries",
        "nopage-entries": "http://127.0.0.1:8000/nopage-entries",
        "authors": "http://127.0.0.1:8000/authors",
        "comments": "http://127.0.0.1:8000/comments",
        "companies": "http://127.0.0.1:8000/companies",
        "projects": "http://127.0.0.1:8000/projects"
    }
}

Then try a GET http://127.0.0.1:8000/entries to see a pretty interesting response that demonstrates relationships and included:

{
    "links": {
        "first": "http://127.0.0.1:8000/entries?page=1",
        "last": "http://127.0.0.1:8000/entries?page=1",
        "next": null,
        "prev": null
    },
    "data": [
        {
            "type": "posts",
            "id": "1",
            "attributes": {
                "headline": "This is a test, this is only a test",
                "bodyText": "And this is the body text for the blog entry. To see comments included in this payload visit: /entries/1?include=comments",
                "pubDate": "2015-01-01",
                "modDate": "2015-04-05"
            },
            "relationships": {
                "blog": {
                    "data": {
                        "type": "blog",
                        "id": "1"
                    }
                },
                "blogHyperlinked": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/1/relationships/blog_hyperlinked",
                        "related": "http://127.0.0.1:8000/entries/1/blog"
                    }
                },
                "authors": {
                    "meta": {
                        "count": 1
                    },
                    "data": [
                        {
                            "type": "author",
                            "id": "1"
                        }
                    ]
                },
                "comments": {
                    "meta": {
                        "count": 1
                    },
                    "data": [
                        {
                            "type": "comment",
                            "id": "1"
                        }
                    ]
                },
                "commentsHyperlinked": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/1/relationships/comments_hyperlinked",
                        "related": "http://127.0.0.1:8000/entries/1/comments"
                    }
                },
                "suggested": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/1/relationships/suggested",
                        "related": "http://127.0.0.1:8000/entries/1/suggested/"
                    },
                    "data": [
                        {
                            "type": "entry",
                            "id": "2"
                        }
                    ]
                },
                "suggestedHyperlinked": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/1/relationships/suggested_hyperlinked",
                        "related": "http://127.0.0.1:8000/entries/1/suggested/"
                    }
                },
                "tags": {
                    "data": []
                },
                "featuredHyperlinked": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/1/relationships/featured_hyperlinked",
                        "related": "http://127.0.0.1:8000/entries/1/featured"
                    }
                }
            },
            "meta": {
                "bodyFormat": "text"
            }
        },
        {
            "type": "posts",
            "id": "2",
            "attributes": {
                "headline": "Django, the framework for perfectionists with deadlines",
                "bodyText": "And this is the body text. Try out includes by using this uri: /entries/2?include=comments,authors,authors.bio",
                "pubDate": "2015-05-01",
                "modDate": "2015-09-03"
            },
            "relationships": {
                "blog": {
                    "data": {
                        "type": "blog",
                        "id": "1"
                    }
                },
                "blogHyperlinked": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/2/relationships/blog_hyperlinked",
                        "related": "http://127.0.0.1:8000/entries/2/blog"
                    }
                },
                "authors": {
                    "meta": {
                        "count": 1
                    },
                    "data": [
                        {
                            "type": "author",
                            "id": "2"
                        }
                    ]
                },
                "comments": {
                    "meta": {
                        "count": 1
                    },
                    "data": [
                        {
                            "type": "comment",
                            "id": "2"
                        }
                    ]
                },
                "commentsHyperlinked": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/2/relationships/comments_hyperlinked",
                        "related": "http://127.0.0.1:8000/entries/2/comments"
                    }
                },
                "suggested": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/2/relationships/suggested",
                        "related": "http://127.0.0.1:8000/entries/2/suggested/"
                    },
                    "data": [
                        {
                            "type": "entry",
                            "id": "1"
                        }
                    ]
                },
                "suggestedHyperlinked": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/2/relationships/suggested_hyperlinked",
                        "related": "http://127.0.0.1:8000/entries/2/suggested/"
                    }
                },
                "tags": {
                    "data": []
                },
                "featuredHyperlinked": {
                    "links": {
                        "self": "http://127.0.0.1:8000/entries/2/relationships/featured_hyperlinked",
                        "related": "http://127.0.0.1:8000/entries/2/featured"
                    }
                }
            },
            "meta": {
                "bodyFormat": "text"
            }
        }
    ],
    "included": [
        {
            "type": "comment",
            "id": "1",
            "attributes": {
                "body": "Love this article!"
            },
            "relationships": {
                "writer": {
                    "data": {
                        "type": "writers",
                        "id": "2"
                    }
                },
                "entry": {
                    "data": {
                        "type": "entry",
                        "id": "1"
                    }
                },
                "author": {
                    "data": {
                        "type": "author",
                        "id": "2"
                    }
                }
            }
        },
        {
            "type": "comment",
            "id": "2",
            "attributes": {
                "body": "Frist comment!!!"
            },
            "relationships": {
                "writer": {
                    "data": null
                },
                "entry": {
                    "data": {
                        "type": "entry",
                        "id": "2"
                    }
                },
                "author": {
                    "data": null
                }
            }
        }
    ],
    "meta": {
        "pagination": {
            "page": 1,
            "pages": 1,
            "count": 2
        }
    }
}

Note that there are still deficiencies with the example app that I would like to fix (or please submit a PR!):

• Fix pagination to use the suggested style of page[number]= instead of just page. See the JsonApiPageNumberPagination in the usage docs.
• Implement additional filter features currently WIP in WIP: Filter Backends #455.
• Add related
• Add HyperlinkedRelatedField and SerializerMethodHyperlinkedRelatedField. (Add HyperlinkedRelatedField and SerializerMethodHyperlinkedRelatedField fields #445)
• more....

[ThibaultLemaire]

Thanks, I can confirm that those steps work 👍 (Tested on Debian 9 (stretch) 64-bit).

As is, this is already great material to get a grasp of what dja can do.