Verified Commit ed5d259c authored by David Haynes's avatar David Haynes 🙆
Browse files

v2 documentation for ViewSets

- now with markdown
- crispy forms used for better modals
- coreapi added per docs
parent 1e9404aa
......@@ -10,3 +10,6 @@ django-taggit-serializer==0.1.5
six==1.10.0
djangorestframework-gis==0.11.2
django-filter==1.0.4
django-crispy-forms==1.6.1
markdown==2.6.8
coreapi==2.3.1
......@@ -2,6 +2,9 @@
api/views.py
Rest Framework Class Views
Each ViewSet determines what data is returned when an API endpoint is hit. In
addition, we define filtering and documentation for each of these endpoints.
"""
# Future Imports
from __future__ import (absolute_import, division, print_function,
......@@ -25,29 +28,61 @@ class AlertViewSet(viewsets.ReadOnlyModelViewSet):
Some type of notification that is displayed to clients that conveys a message.
Past examples include:
- random closings
- modified schedules being in effect
- election reminder
- advertising for other SRCT projects
- Random closings
- Modified schedules being in effect
- Election reminder
- Advertising for other SRCT projects
Alerts last for a period of time until the information is no longer dank.
GET /api/alerts/
---
## Default behavior
[GET /api/alerts/](/api/alerts/?format=json)
Return all Alert objects.
Built-in query parameters:
## Built-in query parameters
### **Search**
[GET /api/alerts/?search=](/api/alerts/?search=&format=json)
GET /api/alerts/?search=
Query parameter that returns objects that match a keyword provided in the search.
GET /api/alerts/?ordering=
**Example Usage**
[GET /api/alerts/?search=srct](/api/alerts/?search=srct&format=json)
Return any Alert objects that have the string "srct" located in one of its fields.
### **Ordering**
[GET /api/alerts/?ordering=](/api/alerts/?ordering=&format=json)
Query parameter that orders the returned objects based on the provided field to order by.
Additionally, you can query against any field you like:
**Example Usage**
[GET /api/alerts/?ordering=urgency_tag](/api/alerts/?ordering=urgency_tag&format=json)
ie.
GET /api/alerts/?urgency_tag=major
will return the Alert objects that are tagged as "major" urgency.
Return all Alert objects ordered by urgency_tag ascending.
[GET /api/alerts/?ordering=-urgency_tag](/api/alerts/?ordering=-urgency_tag&format=json)
Return all Alert objects ordered by urgency_tag descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
[GET /api/alerts/?urgency_tag=major](/api/alerts/?urgency_tag=major&format=json)
Return all Alert objects that are tagged as "major" urgency.
"""
# All model fields that are available for filtering
FILTER_FIELDS = (
......@@ -79,27 +114,59 @@ class CategoryViewSet(viewsets.ReadOnlyModelViewSet):
"""
A Category is a grouping of Facilities that serve a common/similar purpose.
ex.
- Dining
- Gyms
- Study areas (Libraries, The Ridge, JC, etc)
Examples:
- Dining
- Gyms
- Study areas (Libraries, The Ridge, JC, etc)
---
## Default behavior
[GET /api/categories/](/api/categories/)
GET /api/categories/
Return all Category objects.
Built-in query parameters:
## Built-in query parameters
### **Search**
[GET /api/categories/?search=](/api/categories/?search=&format=json)
GET /api/categories/?search=
Query parameter that returns objects that match a keyword provided in the search.
GET /api/categories/?ordering=
**Example Usage**
[GET /api/categories/?search=din](/api/categories/?search=din&format=json)
Return all Category objects that have a field that matches the string "din".
### **Ordering**
[GET /api/categories/?ordering=](/api/categories/?ordering=&format=json)
Query parameter that orders the returned objects based on the provided field to order by.
Additionally, you can query against any field you like:
**Example Usage**
[GET /api/categories/?ordering=name](/api/categories/?ordering=name&format=json)
Return all Category objects filtered by name ascending.
[GET /api/categories/?ordering=-name](/api/categories/?ordering=-name&format=json)
Return all Category objects filtered by name descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
ie.
GET /api/categories/?name=dining
will return the Category object that is named "dining".
[GET /api/categories/?name=dining](/api/categories/?name=dining&format=json)
Return the Category object that is named "dining".
"""
# All model fields that are available for filtering
FILTER_FIELDS = (
......@@ -128,22 +195,53 @@ class LocationViewSet(viewsets.ReadOnlyModelViewSet):
"""
Represents a specific location that a Facility can be found.
GET /api/locations/
---
## Default behavior
[GET /api/locations/](/api/locations/?format=json)
Return all Location objects.
Built-in query parameters:
## Built-in query parameters
### **Search**
[GET /api/locations/?search=](/api/locations/?search=&format=json)
GET /api/locations/?search=
Query parameter that returns objects that match a keyword provided in the search.
GET /api/locations/?ordering=
Query parameter that orders the returned objects based on the provided field to order by.
**Example Usage**
[GET /api/locations/?search=johnson](/api/locations/?search=johnson&format=json)
Return all Location objects that have a field that matches the "johnson" string.
### **Ordering**
Order the returned objects based on the provided field.
[GET /api/locations/?ordering=](/api/locations/?ordering=&format=json)
Additionally, you can query against any field you like:
**Example Usage**
ie.
GET /api/locations/?building=Johnson+Center
will return all Location objects located in the "Johnson Center" building.
[GET /api/locations/?ordering=building](/api/locations/?ordering=building&format=json)
Return all Location objects ordered by building name ascending.
[GET /api/locations/?ordering=-building](/api/locations/?ordering=-building&format=json)
Return all Location objects ordered by building name descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
[GET /api/locations/?building=Johnson+Center](/api/locations/?building=Johnson+Center&format=json)
Return all Location objects located in the "Johnson Center" building.
"""
# All model fields that are available for filtering
FILTER_FIELDS = (
......@@ -174,30 +272,67 @@ class FacilityViewSet(viewsets.ReadOnlyModelViewSet):
"""
A Facility is some type of establishment that has a schedule of open hours and a location that serves a specific purpose that can be categorized.
GET /api/facilities/
Return all Facility objects. We additionally filter out stale special_schedules to reduce client side calculations.
---
## Default behavior
[GET /api/facilities/](/api/facilities/?format=json)
Return all Facility objects. Additionally, we filter out stale special_schedules to reduce client side calculations.
## Built-in query parameters
### **Search**
Built-in query parameters:
[GET /api/facilities/?search=](/api/facilities/?search=&format=json)
GET /api/facilities/?search=
Query parameter that returns objects that match a keyword provided in the search.
GET /api/facilities/?ordering=
**Example Usage**
[GET /api/facilities/?search=south](/api/facilities/?search=south&format=json)
Return all Facility objects that have a field that matches the string "south".
### **Ordering**
[GET /api/facilities/?ordering=](/api/facilities/?ordering=&format=json)
Query parameter that orders the returned objects based on the provided field to order by.
Additionally, you can query against any field you like:
**Example Usage**
[GET /api/facilities/?ordering=facility_name](/api/facilities/?ordering=facility_name&format=json)
Return all Facility objects ordered by facility_name ascending.
[GET /api/facilities/?ordering=-facility_name](/api/facilities/?ordering=-facility_name&format=json)
Return all Facility objects ordered by facility_name descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
ie.
GET /api/facilities/?facility_name=Southside
will return the Facility object that has "Southside" as its name.
[GET /api/facilities/?facility_name=Southside](/api/facilities/?facility_name=Southside&format=json)
Custom query parameters:
Return the Facility object that has "Southside" as its name.
GET /api/facilities/?open_now
Query parameter that only returns open Facility objects.
## Custom query parameters
GET /api/facilities/?closed_now
Query parameter that only returns closed Facility objects.
### **open_now**
[GET /api/facilities/?open_now](/api/facilities/?open_now&format=json)
Only return open Facility objects.
### **closed_now**
[GET /api/facilities/?closed_now](/api/facilities/?closed_now&format=json)
Only return closed Facility objects.
"""
# All model fields that are available for filtering
FILTER_FIELDS = (
......@@ -265,22 +400,56 @@ class ScheduleViewSet(viewsets.ModelViewSet):
"""
A period of time between two dates that represents the beginning and end of a "schedule" or rather, a collection of open times for a facility.
GET /api/schedules/
---
## Default behavior
[GET /api/schedules/](/api/schedules/?format=json)
Return all Schedule objects that have not expired. (ie. end_date is before today)
Built-in query parameters:
## Built-in query parameters
### **Search**
[GET /api/schedules/?search=](/api/schedules/?search=&format=json)
GET /api/schedules/?search=
Query parameter that returns objects that match a keyword provided in the search.
GET /api/schedules/?ordering=
**Example Usage**
[GET /api/schedules/?search=south](/api/schedules/?search=south&format=json)
Return all Schedule objects that have a field matching the string "south".
### **Ordering**
[GET /api/schedules/?ordering=](/api/schedules/?ordering=&format=json)
Query parameter that orders the returned objects based on the provided field to order by.
Additionally, you can query against any field you like:
**Example Usage**
[GET /api/schedules/?ordering=name](/api/schedules/?ordering=name&format=json)
Return all Schedule objects ordered by name ascending.
[GET /api/schedules/?ordering=-name](/api/schedules/?ordering=-name&format=json)
[GET /api/schedules/?ordering=name](/api/schedules/?ordering=name&format=json)
Return all Schedule objects ordered by name ascending.
Return all Schedule objects ordered by name descending.
### **Field filtering**
You can query directly against any field.
**Example Usage**
[GET /api/schedules/?name=southside_main](/api/schedules/?name=southside_main&format=json)
ie.
GET /api/schedules/?name=southside_main
will return the Schedule object that has "southside_main" as its name.
Return the Schedule object that has "southside_main" as its name.
"""
# All model fields that are available for filtering
FILTER_FIELDS = (
......
......@@ -245,6 +245,7 @@ INSTALLED_APPS = (
'rest_framework',
'rest_framework_gis',
'django_filters',
'crispy_forms',
)
"""
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment