From 315e81ea81848f7bdcb9b6a46a8f6fa59f3e91bc Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Tue, 6 Oct 2020 13:22:29 -0700 Subject: [PATCH 1/9] add installation instructions --- README.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5d3c1e6 --- /dev/null +++ b/README.md @@ -0,0 +1,136 @@ +# Django REST Framework Contacts API Template + +## Description + +This is a single model full CRUD API for contacts using Python and Django. + +> This is an **api only**. I would suggest consuming this API using React as a _separate server_ by using [create-react-app](https://reactjs.org/docs/create-a-new-react-app.html). + +### Contacts Properties: + +|Property | Type | Default | +|---|---|---| +| id | integer | assigned by db | +| name | string | n/a | +| age | int | n/a | + +### Contacts Routes: + +|Endpoint | Action | +|---|---| +| `/api/contacts` | GET (Index) | +| `/api/contacts/:id` | GET (Show) | +| `/api/contacts` | POST | +| `/api/contacts/:id` | DELETE | +| `/api/contacts/:id` | PUT | + +## System Requirements + +- Python 3 +- pipenv + +### Installation + +If you don't have either of the above, please install them. + +
Python3 Installation

+ +#### Python Installation + +1. Check what python version you have on your computer by running: `python -V` +1. If you're not on a version of Python that is 3 or greater, install python 3 with homebrew: + - `brew install python3` + - Note: in order to use this installed python3, you will have to use `python3` whenever running a python command + +

+ +
pipenv Installation

+ +#### pipenv Installation + +To build your app, we're going to be building a virtual environment. In order to manage our dependencies and our virtual environment, we're going to use [pipenv](https://pipenv.pypa.io/en/latest/). + +1. Check if you have pipenv by running: `pipenv --version` +1. If you do not have it, install it with homebrew: + - `brew install pipenv` + +

+ +--- + +## Get Set Up Locally + +### On your Browser + +1. Fork this repository to your account + +### In your Terminal + +1. Clone **your fork** of the repo onto your computer anywhere that is not a git repo +1. `cd` into the repo +1. Touch a `.env` into the root of your project and add a SECRET_KEY value. See the .env.sample file for an example +1. Install all the required packages by running: `pipenv install` +1. Activate the virtual environment by running: `pipenv shell` + - NOTE: To exit the shell gracefully whenever you're done working, use `exit` +1. Create the `django_contacts` psql database and user by running: `psql -U postgres -f settings.sql` + - You can find the database name and username/password inside the settings.sql file +1. Apply the migrations by running: `python3 manage.py migrate` +1. Make a superuser for your app, this will allow you to work directly with your database on the browser without having to use Postman + - In the pipenv shell, run `python3 manage.py createsuperuser` and follow the instructions +1. Start the Django server by running the following inside the pipenv shell: `python3 manage.py runserver` + +### On your Browser + +1. Go to `localhost:8000/api/contacts`. You should see the Django REST Framework interface like so: +![](https://imgur.com/V6SvjaX.png) +1. Click the `Log In` on the top right corner and use the username/password you created when making the superuser +1. You should now be able to add / delete / edit / read contacts directly from your browser + +--- + +## Making Changes + +### Updating / Creating Models + +1. If you make any changes to the `contacts_api/models.py` file, you will need to make and run a migration to apply the changes. Do the following commands while _inside the pipenv shell_ + 1. Make the migration: `python3 manage.py makemigrations` + 1. Apply the migration: `python3 manage.py migrate` + +--- + +## Set Up for Heroku Deployment + +### In Terminal +1. Create a heroku app from the root of your project folder, run: `heroku create` + - The above command will randomly generate a name for you, if you want to name your app something specific run: `heroku create urlNameYouWantHere` + +### In your Code Editor + +1. Copy the heroku url that was created (without the `https://`), go to your `django_rest_api/settings.py` and add it into the `ALLOWED_HOSTS` + - e.g. + ![](https://imgur.com/AVlB8kK.png) + +### On the Browser + +1. Go to your heroku dashboard for the heroku project you just created +1. Click on Configure Add-Ons +1. Search for Heroku Postgres and add it +1. Go to the Settings, Reveal Config Vars, add a config var for SECRET_KEY and anything else you have in your .env file + +### In Terminal + +1. `pipenv lock` to ensure your pipfile.lock is up to date +1. `git add -A` +1. `git commit -m "heroku deployment"` +1. `git push heroku master` +1. Once it builds successfully, run `heroku run bash` +1. While in heroku bash, apply the migrations to the heroku project by running: `python manage.py migrate` +1. Still in heroku bash, create a superuser for the heroku project by running `python + - To exit heroku bash, run `exit` + +### In Browser + +1. After the migrations finish, you should now be able to open the heroku app and use this deployed version as your backend API + - Don't forget to go to `/api/contacts` +1. Remember that your heroku database is separate from your local database, so there should not be any data on the first load. + - You can add data by logging in with the heroku superuser you created From e8c9694d0c704d9cc35933b61f3ab0bed2c200bc Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Tue, 6 Oct 2020 13:28:47 -0700 Subject: [PATCH 2/9] specify when using pipenv shell bash --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5d3c1e6..392cdb6 100644 --- a/README.md +++ b/README.md @@ -72,9 +72,9 @@ To build your app, we're going to be building a virtual environment. In order to 1. Install all the required packages by running: `pipenv install` 1. Activate the virtual environment by running: `pipenv shell` - NOTE: To exit the shell gracefully whenever you're done working, use `exit` -1. Create the `django_contacts` psql database and user by running: `psql -U postgres -f settings.sql` +1. Create the `django_contacts` psql database and user by running the following while in the pipenv shell: `psql -U postgres -f settings.sql` - You can find the database name and username/password inside the settings.sql file -1. Apply the migrations by running: `python3 manage.py migrate` +1. Apply the migrations by running the following while in the pipenv shell: `python3 manage.py migrate` 1. Make a superuser for your app, this will allow you to work directly with your database on the browser without having to use Postman - In the pipenv shell, run `python3 manage.py createsuperuser` and follow the instructions 1. Start the Django server by running the following inside the pipenv shell: `python3 manage.py runserver` @@ -92,7 +92,7 @@ To build your app, we're going to be building a virtual environment. In order to ### Updating / Creating Models -1. If you make any changes to the `contacts_api/models.py` file, you will need to make and run a migration to apply the changes. Do the following commands while _inside the pipenv shell_ +1. If you make any changes to the `contacts_api/models.py` file, you will need to make and run a migration to apply the changes. You can do so by using the following commands while _inside the pipenv shell_ 1. Make the migration: `python3 manage.py makemigrations` 1. Apply the migration: `python3 manage.py migrate` From 3d5919143fd466f614747b01a91a2ad8c5a827b7 Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Tue, 6 Oct 2020 13:30:38 -0700 Subject: [PATCH 3/9] finish sentence --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 392cdb6..7f03f8a 100644 --- a/README.md +++ b/README.md @@ -125,7 +125,7 @@ To build your app, we're going to be building a virtual environment. In order to 1. `git push heroku master` 1. Once it builds successfully, run `heroku run bash` 1. While in heroku bash, apply the migrations to the heroku project by running: `python manage.py migrate` -1. Still in heroku bash, create a superuser for the heroku project by running `python +1. Still in heroku bash, create a superuser for the heroku project by running `python manage.py createsuperuser` and follow the prompts - To exit heroku bash, run `exit` ### In Browser From 902ebdebdf327cb0c9f4eadc47e5f9e70f1fccfb Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Tue, 6 Oct 2020 13:31:37 -0700 Subject: [PATCH 4/9] fix wording --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7f03f8a..a91e35d 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,8 @@ To build your app, we're going to be building a virtual environment. In order to ### In Browser -1. After the migrations finish, you should now be able to open the heroku app and use this deployed version as your backend API +1. After the migrations finish, you should now be able to open the heroku app in your browser to see the same Django REST interface! - Don't forget to go to `/api/contacts` 1. Remember that your heroku database is separate from your local database, so there should not be any data on the first load. - You can add data by logging in with the heroku superuser you created +1. You can now use this deployed version as your backend API From bf62c077dd07c90d46deabca4a1dc06a0cd052ff Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Tue, 6 Oct 2020 13:44:02 -0700 Subject: [PATCH 5/9] add resources --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index a91e35d..7e6d6c7 100644 --- a/README.md +++ b/README.md @@ -135,3 +135,24 @@ To build your app, we're going to be building a virtual environment. In order to 1. Remember that your heroku database is separate from your local database, so there should not be any data on the first load. - You can add data by logging in with the heroku superuser you created 1. You can now use this deployed version as your backend API + +--- + +## Resources + +Django and Rest are both fairly opinionated frameworks meaning there are right ways to do things. If you plan on making many changes to this template, I would recommend looking at their documentation: + +- [Django Documentation](https://docs.djangoproject.com/en/3.1/) + - Particular pages you may want to look at: + - [Making Queries (Django's built in ORM)](https://docs.djangoproject.com/en/3.1/topics/db/queries/#) + - [Models](https://docs.djangoproject.com/en/3.1/topics/db/models/) + - [Migrations](https://docs.djangoproject.com/en/2.0/topics/migrations/) + - [URLs Config](https://docs.djangoproject.com/en/3.1/topics/http/urls/) + +- [Djagno REST Framework Documentation](https://www.django-rest-framework.org/) (Click on the API Guide dropdown on the nav bar to see their documentation for specific things) + - Particular pages you may want to look at: + - [Serializers](https://www.django-rest-framework.org/api-guide/serializers/) + - [Class-based views](https://www.django-rest-framework.org/api-guide/views/) + - [Generic views](https://www.django-rest-framework.org/api-guide/generic-views/) + - [ViewSets](https://www.django-rest-framework.org/api-guide/viewsets/) + - [Routers](https://www.django-rest-framework.org/api-guide/routers/) From a79d8baff25f89f785656112cc3bfa2980cc849e Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Tue, 6 Oct 2020 13:47:14 -0700 Subject: [PATCH 6/9] fix wording for consistency --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7e6d6c7..c17cb44 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ This is a single model full CRUD API for contacts using Python and Django. |---|---|---| | id | integer | assigned by db | | name | string | n/a | -| age | int | n/a | +| age | integer | n/a | ### Contacts Routes: From 319e9e2c5fad374a0f298b887ccfdf91bc5125a3 Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Tue, 6 Oct 2020 13:52:48 -0700 Subject: [PATCH 7/9] remove a word --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c17cb44..c702f98 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ To build your app, we're going to be building a virtual environment. In order to ### In Browser -1. After the migrations finish, you should now be able to open the heroku app in your browser to see the same Django REST interface! +1. After the migrations finish, you should now be able to open the heroku app in your browser to see the Django REST interface! - Don't forget to go to `/api/contacts` 1. Remember that your heroku database is separate from your local database, so there should not be any data on the first load. - You can add data by logging in with the heroku superuser you created From d5ee1765f37403bcaf7dd6567bee20bdbcc214a7 Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Thu, 8 Oct 2020 11:44:24 -0700 Subject: [PATCH 8/9] add rest framework --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c702f98..92db5aa 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## Description -This is a single model full CRUD API for contacts using Python and Django. +This is a single model full CRUD API for contacts using Python, Django, and the Django REST Framework. > This is an **api only**. I would suggest consuming this API using React as a _separate server_ by using [create-react-app](https://reactjs.org/docs/create-a-new-react-app.html). From d6326ea5b838dd85c050b8850317d6b471f93aed Mon Sep 17 00:00:00 2001 From: Jerrica Bobadilla Date: Thu, 8 Oct 2020 12:05:55 -0700 Subject: [PATCH 9/9] fix documentation link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 92db5aa..e8ca809 100644 --- a/README.md +++ b/README.md @@ -146,7 +146,7 @@ Django and Rest are both fairly opinionated frameworks meaning there are right w - Particular pages you may want to look at: - [Making Queries (Django's built in ORM)](https://docs.djangoproject.com/en/3.1/topics/db/queries/#) - [Models](https://docs.djangoproject.com/en/3.1/topics/db/models/) - - [Migrations](https://docs.djangoproject.com/en/2.0/topics/migrations/) + - [Migrations](https://docs.djangoproject.com/en/3.1/topics/migrations/) - [URLs Config](https://docs.djangoproject.com/en/3.1/topics/http/urls/) - [Djagno REST Framework Documentation](https://www.django-rest-framework.org/) (Click on the API Guide dropdown on the nav bar to see their documentation for specific things)