Skip to content

Commit 47a0f75

Browse files
author
Juan Benitez
committed
docs: update readme
1 parent dd336ca commit 47a0f75

File tree

2 files changed

+75
-33
lines changed

2 files changed

+75
-33
lines changed

‎README.md

Lines changed: 73 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,21 @@
33

44
## Requirements
55
- Python 3.6
6-
- Django (2.1)
6+
- Django 3.1
77
- Django REST Framework
8-
- Django Rest Auth
98

109
## Installation
10+
After you cloned the repository, you want to create a virtual environment, so you have a clean python installation.
11+
You can do this by running the command
1112
```
12-
pip install django
13-
pip install djangorestframework
14-
pip install django-rest-auth
15-
pip install django-allauth
13+
python -m venv env
14+
```
15+
16+
After this, it is necessary to activate the virtual environment, you can get more information about this [here](https://docs.python.org/3/tutorial/venv.html)
17+
18+
You can install all the required dependencies by running
19+
```
20+
pip install -r requirements.txt
1621
```
1722

1823
## Structure
@@ -29,7 +34,9 @@ Endpoint |HTTP Method | CRUD Method | Result
2934
`movies/:id` | DELETE | DELETE | Delete a movie
3035

3136
## Use
32-
We can test the API using [curl](https://curl.haxx.se/) or [httpie](https://github.com/jakubroztocil/httpie#installation). Httpie is a user friendly http client that's written in Python. Let's install that.
37+
We can test the API using [curl](https://curl.haxx.se/) or [httpie](https://github.com/jakubroztocil/httpie#installation), or we can use [Postman](https://www.postman.com/)
38+
39+
Httpie is a user-friendly http client that's written in Python. Let's try and install that.
3340

3441
You can install httpie using pip:
3542
```
@@ -38,70 +45,105 @@ pip install httpie
3845

3946
First, we have to start up Django's development server.
4047
```
41-
python manage.py runserver
48+
python manage.py runserver
4249
```
4350
Only authenticated users can use the API services, for that reason if we try this:
4451
```
45-
http http://127.0.0.1:8000/api/v1/movies/3
52+
http http://127.0.0.1:8000/api/v1/movies/
4653
```
4754
we get:
4855
```
49-
{ "detail": "You must be authenticated" }
56+
{
57+
"detail": "Authentication credentials were not provided."
58+
}
5059
```
5160
Instead, if we try to access with credentials:
5261
```
53-
http http://127.0.0.1:8000/api/v1/movies/3 "Authorization: Token 7530ec9186a31a5b3dd8d03d84e34f80941391e3"
62+
http http://127.0.0.1:8000/api/v1/movies/3 "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjE2MjA4Mjk1LCJqdGkiOiI4NGNhZmMzMmFiZDA0MDQ2YjZhMzFhZjJjMmRiNjUyYyIsInVzZXJfaWQiOjJ9.NJrs-sXnghAwcMsIWyCvE2RuGcQ3Hiu5p3vBmLkHSvM"
5463
```
5564
we get the movie with id = 3
5665
```
5766
{ "title": "Avengers", "genre": "Superheroes", "year": 2012, "creator": "admin" }
5867
```
5968

60-
## Login and Tokens
69+
## Create users and Tokens
6170

62-
To get a token first we have to login
71+
First we need to create a user, so we can log in
72+
```
73+
http POST http://127.0.0.1:8000/api/v1/auth/register/ email="[email protected]" username="USERNAME" password1="PASSWORD" password2="PASSWORD"
6374
```
64-
http http://127.0.0.1:8000/rest-auth/login/ username="admin" password="root1234"
75+
76+
After we create an account we can use those credentials to get a token
77+
78+
To get a token first we need to request
79+
```
80+
http http://127.0.0.1:8000/api/v1/auth/token/ username="username" password="password"
6581
```
6682
after that, we get the token
6783
```
6884
{
69-
"key": "2d500db1e51153318e300860064e52c061e72016"
85+
"refresh": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTYxNjI5MjMyMSwianRpIjoiNGNkODA3YTlkMmMxNDA2NWFhMzNhYzMxOTgyMzhkZTgiLCJ1c2VyX2lkIjozfQ.hP1wPOPvaPo2DYTC9M1AuOSogdRL_mGP30CHsbpf4zA",
86+
"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjE2MjA2MjIxLCJqdGkiOiJjNTNlNThmYjE4N2Q0YWY2YTE5MGNiMzhlNjU5ZmI0NSIsInVzZXJfaWQiOjN9.Csz-SgXoItUbT3RgB3zXhjA2DAv77hpYjqlgEMNAHps"
7087
}
7188
```
72-
**ALL request must be authenticated with a valid token, otherwise they will be invalid**
89+
We got two tokens, the access token will be used to authenticated all the requests we need to make, this access token will expire after some time.
90+
We can use the refresh token to request a need access token.
7391

74-
We can create new users. (password1 and password2 must be equal)
92+
requesting new access token
7593
```
76-
http POST http://127.0.0.1:8000/rest-auth/registration/ username="USERNAME" password1="PASSWORD" password2="PASSWORD"
94+
http http://127.0.0.1:8000/api/v1/auth/token/refresh/ refresh="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTYxNjI5MjMyMSwianRpIjoiNGNkODA3YTlkMmMxNDA2NWFhMzNhYzMxOTgyMzhkZTgiLCJ1c2VyX2lkIjozfQ.hP1wPOPvaPo2DYTC9M1AuOSogdRL_mGP30CHsbpf4zA"
7795
```
78-
And we can logout, the token must be your actual token
96+
and we will get a new access token
7997
```
80-
http POST http://127.0.0.1:8000/rest-auth/logout/ "Authorization: Token <YOUR_TOKEN>"
98+
{
99+
"access": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNjE2MjA4Mjk1LCJqdGkiOiI4NGNhZmMzMmFiZDA0MDQ2YjZhMzFhZjJjMmRiNjUyYyIsInVzZXJfaWQiOjJ9.NJrs-sXnghAwcMsIWyCvE2RuGcQ3Hiu5p3vBmLkHSvM"
100+
}
81101
```
82102

103+
83104
The API has some restrictions:
84105
- The movies are always associated with a creator (user who created it).
85106
- Only authenticated users may create and see movies.
86107
- Only the creator of a movie may update or delete it.
87-
- Unauthenticated requests shouldn't have access.
108+
- The API doesn't allow unauthenticated requests.
88109

89110
### Commands
90111
```
91-
http http://127.0.0.1:8000/api/v1/movies/ "Authorization: Token <YOUR_TOKEN>"
92-
http GET http://127.0.0.1:8000/api/v1/movies/3 "Authorization: Token <YOUR_TOKEN>"
93-
http POST http://127.0.0.1:8000/api/v1/movies/ "Authorization: Token <YOUR_TOKEN>" title="Ant Man and The Wasp" genre="Action" year=2018
94-
http PUT http://127.0.0.1:8000/api/v1/movies/3 "Authorization: Token <YOUR_TOKEN>" title="AntMan and The Wasp" genre="Action" year=2018
95-
http DELETE http://127.0.0.1:8000/api/v1/movies/3 "Authorization: Token <YOUR_TOKEN>"
112+
Get all movies
113+
http http://127.0.0.1:8000/api/v1/movies/ "Authorization: Bearer {YOUR_TOKEN}"
114+
Get a single movie
115+
http GET http://127.0.0.1:8000/api/v1/movies/{movie_id}/ "Authorization: Bearer {YOUR_TOKEN}"
116+
Create a new movie
117+
http POST http://127.0.0.1:8000/api/v1/movies/ "Authorization: Bearer {YOUR_TOKEN}" title="Ant Man and The Wasp" genre="Action" year=2018
118+
Full update a movie
119+
http PUT http://127.0.0.1:8000/api/v1/movies/{movie_id}/ "Authorization: Bearer {YOUR_TOKEN}" title="AntMan and The Wasp" genre="Action" year=2018
120+
Partial update a movie
121+
http PATCH http://127.0.0.1:8000/api/v1/movies/{movie_id}/ "Authorization: Bearer {YOUR_TOKEN}" title="AntMan and The Wasp"
122+
Delete a movie
123+
http DELETE http://127.0.0.1:8000/api/v1/movies/{movie_id}/ "Authorization: Bearer {YOUR_TOKEN}"
96124
```
97125

98126
### Pagination
99-
The API supports pagination, by default responses have a page_size=10 but if you want change that you can pass through params page=size=X
127+
The API supports pagination, by default responses have a page_size=10 but if you want change that you can pass through params page_size={your_page_size_number}
100128
```
101-
http http://127.0.0.1:8000/api/v1/movies/?page=1 "Authorization: Token <YOUR_TOKEN>"
102-
http http://127.0.0.1:8000/api/v1/movies/?page=3 "Authorization: Token <YOUR_TOKEN>"
103-
http http://127.0.0.1:8000/api/v1/movies/?page=3&page_size=15 "Authorization: Token <YOUR_TOKEN>"
129+
http http://127.0.0.1:8000/api/v1/movies/?page=1 "Authorization: Bearer {YOUR_TOKEN}"
130+
http http://127.0.0.1:8000/api/v1/movies/?page=3 "Authorization: Bearer {YOUR_TOKEN}"
131+
http http://127.0.0.1:8000/api/v1/movies/?page=3&page_size=15 "Authorization: Bearer {YOUR_TOKEN}"
104132
```
105133

106-
Finally, I provide a DB to make these tests.
134+
### Filters
135+
The API supports filtering, you can filter by the attributes of a movie like this
136+
```
137+
http http://127.0.0.1:8000/api/v1/movies/?title="AntMan" "Authorization: Bearer {YOUR_TOKEN}"
138+
http http://127.0.0.1:8000/api/v1/movies/?year=2020 "Authorization: Bearer {YOUR_TOKEN}"
139+
http http://127.0.0.1:8000/api/v1/movies/?year__gt=2019&year__lt=2022 "Authorization: Bearer {YOUR_TOKEN}"
140+
http http://127.0.0.1:8000/api/v1/movies/?genre="Action" "Authorization: Bearer {YOUR_TOKEN}"
141+
http http://127.0.0.1:8000/api/v1/movies/?creator__username="myUsername" "Authorization: Bearer {YOUR_TOKEN}"
142+
```
143+
144+
You can also combine multiples filters like so
145+
```
146+
http http://127.0.0.1:8000/api/v1/movies/?title="AntMan"&year=2020 "Authorization: Bearer {YOUR_TOKEN}"
147+
http http://127.0.0.1:8000/api/v1/movies/?year__gt=2019&year__lt=2022&genre="Action" "Authorization: Bearer {YOUR_TOKEN}"
148+
```
107149

‎api_crud/urls.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
# urls
66
urlpatterns = [
7-
path('api/movies/', include('movies.urls')),
8-
path('api/auth/', include('authentication.urls')),
7+
path('api/v1/movies/', include('movies.urls')),
8+
path('api/v1/auth/', include('authentication.urls')),
99
path('admin/', admin.site.urls),
1010
]

0 commit comments

Comments
 (0)