Skip to content

Commit 4d3d888

Browse files
mir1198yusufmir1198yusuf
committed
Added documentation for Django REST API
1 parent 27c91ec commit 4d3d888

File tree

5 files changed

+96
-2
lines changed

5 files changed

+96
-2
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -73,4 +73,5 @@ So, I learned both of them and built this project.
7373

7474
The project is live at [site](https://bit.ly/feed_django_reactjs_live)
7575

76+
You can see the documentation of APIs at [docs](https://mir1198yusuf1.pythonanywhere.com/api/docs/)
7677

‎feedapi_app/urls.py

+1
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,5 @@
77
path('logout/', knox.views.LogoutView.as_view(), name='knox_logout'),
88
path('posts/', views.PostsView.as_view(), name='posts_url'),
99
path('posts/<int:post_id>/', views.CommentsView.as_view(), name='comments_url'),
10+
path('docs/', views.documentation_view, name='docs_url'),
1011
]

‎feedapi_app/views.py

+7-1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
from rest_framework.views import APIView
1010
from feedapi_app import models
1111
from rest_framework.parsers import MultiPartParser, FormParser
12+
from django.shortcuts import render
1213

1314

1415
# Create your views here.
@@ -95,4 +96,9 @@ def post(self, request, post_id):
9596
serializer.validated_data['post'] = post
9697
serializer.save()
9798
return Response(serializer.data, status=status.HTTP_201_CREATED)
98-
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
99+
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
100+
101+
102+
#docs view function
103+
def documentation_view(request):
104+
return render(request, 'api_docs.html')

‎feedapi_project/settings.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@
6565
TEMPLATES = [
6666
{
6767
'BACKEND': 'django.template.backends.django.DjangoTemplates',
68-
'DIRS': [],
68+
'DIRS': [os.path.join(BASE_DIR, 'templates')],
6969
'APP_DIRS': True,
7070
'OPTIONS': {
7171
'context_processors': [

‎templates/api_docs.html

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
<html>
2+
<head>
3+
<title>Feed APP API documentation</title>
4+
<style>
5+
code{
6+
background-color: lightgrey;
7+
color: black;
8+
}
9+
h1, h3{
10+
color: SlateBlue;
11+
}
12+
</style>
13+
</head>
14+
<body style="font-family: Courier;">
15+
<h1>API documentation</h1>
16+
17+
<p>Django REST framework is used to create REST API</p>
18+
19+
<p>Following API endpoints are created</p>
20+
21+
<ul>
22+
<li>Login endpoint - POST</li>
23+
<li>Logout endpoint - POST</li>
24+
<li>Posts endpoint - GET/POST</li>
25+
<li>Comments endpoint - GET/POST</li>
26+
</ul>
27+
28+
<p><i><b>Note : </b>All api requests example shown here are using httpie library</i></p>
29+
30+
<h3>Login endpoint - POST </h3>
31+
<p>This is used to login a user. We need to pass username, password. In return we get a auth token which we need to pass along with all further subsequent post requests.</p>
32+
<p>You can pass values as form-data or json.</p>
33+
<p><code>http --form post https://mir1198yusuf1.pythonanywhere.com/api/login/ username=username password=password</code></p>
34+
<p><code>http --json post https://mir1198yusuf1.pythonanywhere.com/api/login/ username=username password=password</code></p>
35+
<p>The response data for correct username-password will be : </p>
36+
<p><code>{ "expiry": "2020-07-03T00:06:39.167536+05:30", "token": "xxxxxxxxxxxxx", "username": "username" }</code></p>
37+
<p>For empty/invalid username-password response would be : </p>
38+
<p><code>{"password":["This field may not be blank."],"username":["This field may not be blank."]}</code></p>
39+
<p><code>{"non_field_errors":["Unable to log in with provided credentials."]}</code></p>
40+
41+
<h3>Logout endpoint - POST </h3>
42+
<p>This is used to logout a user. We need to pass auth token received from login endpoint as Authorization header. Once user is logout, the auth token is removed from database & considered as invalid for further post request.</p>
43+
<p>You can pass values as form-data or json.</p>
44+
<p><code>http --form post https://mir1198yusuf1.pythonanywhere.com/api/logout/ 'Authorization: Token xxxxxxxxxxx'</code></p>
45+
<p><code>http --json post https://mir1198yusuf1.pythonanywhere.com/api/logout/ 'Authorization: Token xxxxxxxxxxx'</code></p>
46+
<p>No response data will be returned for correct auth token and user will be logged out.</p>
47+
<p>For empty/invalid token-header response would be : </p>
48+
<p><code>{"detail":"Authentication credentials were not provided."}</code></p>
49+
<p><code>{"detail":"Invalid token."}</code></p>
50+
51+
<h3>Posts endpoint - GET </h3>
52+
<p>This is used to get the list of all posts.</p>
53+
<p><code>http get https://mir1198yusuf1.pythonanywhere.com/api/posts/</code></p>
54+
<p>The response data will be like :</p>
55+
<p><code>[{"created_by":{"email":"[email protected]","id":1,"username":"aaa"},"created_on":"2020-06-18T12:57:40.470161+05:30","created_on_humanized":"2 weeks ago","file":"/media/download.jpeg","id":2,"message":"second post with image"},{"created_by":{"email":"[email protected]","id":1,"username":"aaa"},"created_on":"2020-06-18T12:57:13.274334+05:30","created_on_humanized":"2 weeks ago","file":null,"id":1,"message":"first post"}]</code></p>
56+
57+
<h3>Posts endpoint - POST </h3>
58+
<p>This is used to create a new post. We have to pass auth token in header.</p>
59+
<p>Since it contains a file field, we have to send data in form-data only. no json.</p>
60+
<p>File field is optional but message is mandatory</p>
61+
<p><code>http --form post https://mir1198yusuf1.pythonanywhere.com/api/posts/ message="this is the post message" [email protected] 'Authorization: Token xxxxxxxx'</code></p>
62+
<p>The response data will be created post :</p>
63+
<p><code>{"created_by":{"email":"[email protected]","id":2,"username":"aaa"},"created_on":"2020-07-02T15:15:00.948653+05:30","created_on_humanized":"now","file":"/media/runthis.txt","id":9,"message":"this is the post message"}</code></p>
64+
<p>For empty/invalid values, response can be like :</p>
65+
<p><code>{"detail":"Authentication credentials were not provided."}</code></p>
66+
<p><code>{"message":["This field is required."]}</code></p>
67+
68+
<h3>Comments endpoint - GET </h3>
69+
<p>This is used to get list of all comments for a post. We have to pass a valid post id in url.</p>
70+
<p><code>http get https://mir1198yusuf1.pythonanywhere.com/api/posts/2/</code></p>
71+
<p>The response data will be like :</p>
72+
<p><code>[{"created_by":{"email":"[email protected]","id":1,"username":"aaa"},"created_on":"2020-06-18T13:02:09.492529+05:30","created_on_humanized":"2 weeks ago","id":1,"message":"first comment","post":{"created_by":{"email":"[email protected]","id":1,"username":"aaa"},"created_on":"2020-06-18T12:57:40.470161+05:30","created_on_humanized":"2 weeks ago","file":"/media/download.jpeg","id":2,"message":"second post with image"}}]</code></p>
73+
74+
<h3>Comments endpoint - POST </h3>
75+
<p>This is used to create a new comment for a given post. We have to pass valid post id in url and auth token in header.</p>
76+
<p>We can pass data in both form-data and json format.</p>
77+
<p><code>http --json post https://mir1198yusuf1.pythonanywhere.com/api/posts/1/ message="second comment" 'Authorization: Token xxxxxx'</code></p>
78+
<p><code>http --form post https://mir1198yusuf1.pythonanywhere.com/api/posts/1/ message="second comment" 'Authorization: Token xxxxxx'</code></p>
79+
<p>The response data will be created comment :</p>
80+
<p><code>{"created_by":{"email":"","id":2,"username":"aaa"},"created_on":"2020-07-02T15:29:27.753405+05:30","created_on_humanized":"now","id":4,"message":"second comment","post":{"created_by":{"email":"[email protected]","id":1,"username":"aaa"},"created_on":"2020-06-18T12:57:13.274334+05:30","created_on_humanized":"2 weeks ago","file":null,"id":1,"message":"first post"}}</code></p>
81+
<p>For empty/invalid values, response can be like :</p>
82+
<p><code>{"detail":"Authentication credentials were not provided."}</code></p>
83+
<p><code>{"message":["This field is required."]}</code></p>
84+
85+
</body>
86+
</html>

0 commit comments

Comments
 (0)