From 9bcd4600e0971850e3eae739eb1b350fccbc11f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Laura=20Kl=C3=BCnder?= Date: Wed, 29 Nov 2017 11:27:50 +0100 Subject: [PATCH] add more explanation to the API --- src/c3nav/api/urls.py | 3 ++- src/c3nav/mapdata/api.py | 31 +++++++++++++++++++++++++------ 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/src/c3nav/api/urls.py b/src/c3nav/api/urls.py index e3ce0462..85ffde8e 100644 --- a/src/c3nav/api/urls.py +++ b/src/c3nav/api/urls.py @@ -45,8 +45,9 @@ router.register(r'changesets', ChangeSetViewSet) class APIRoot(GenericAPIView): """ Welcome to the c3nav RESTful API. - The HTML preview is only shown because your Browser sent text/html in it's Accept header. + The HTML preview is only shown because your Browser sent text/html in its Accept header. If you want to use this API on a large scale, please use a client that supports E-Tags. + For more information on a specific API endpoint, access it with a browser. """ def _format_pattern(self, pattern): diff --git a/src/c3nav/mapdata/api.py b/src/c3nav/mapdata/api.py index 1ea8d18d..559ec302 100644 --- a/src/c3nav/mapdata/api.py +++ b/src/c3nav/mapdata/api.py @@ -158,7 +158,10 @@ class MapdataViewSet(ReadOnlyModelViewSet): class LevelViewSet(MapdataViewSet): - """ Add ?on_top_of= to filter by on_top_of, add ?group= to filter by group. """ + """ + Add ?on_top_of= to filter by on_top_of, add ?group= to filter by group. + A Level is a Location – so if it is visible, you can use its ID in the Location API as well. + """ queryset = Level.objects.all() @list_route(methods=['get']) @@ -173,7 +176,10 @@ class BuildingViewSet(MapdataViewSet): class SpaceViewSet(MapdataViewSet): - """ Add ?geometry=1 to get geometries, add ?level= to filter by level, add ?group= to filter by group. """ + """ + Add ?geometry=1 to get geometries, add ?level= to filter by level, add ?group= to filter by group. + A Space is a Location – so if it is visible, you can use its ID in the Location API as well. + """ queryset = Space.objects.all() @list_route(methods=['get']) @@ -193,7 +199,10 @@ class HoleViewSet(MapdataViewSet): class AreaViewSet(MapdataViewSet): - """ Add ?geometry=1 to get geometries, add ?space= to filter by space, add ?group= to filter by group. """ + """ + Add ?geometry=1 to get geometries, add ?space= to filter by space, add ?group= to filter by group. + An Area is a Location – so if it is visible, you can use its ID in the Location API as well. + """ queryset = Area.objects.all() @@ -223,7 +232,10 @@ class ColumnViewSet(MapdataViewSet): class POIViewSet(MapdataViewSet): - """ Add ?geometry=1 to get geometries, add ?space= to filter by space, add ?group= to filter by group. """ + """ + Add ?geometry=1 to get geometries, add ?space= to filter by space, add ?group= to filter by group. + A POI is a Location – so if it is visible, you can use its ID in the Location API as well. + """ queryset = POI.objects.all() @@ -232,13 +244,20 @@ class LocationGroupCategoryViewSet(MapdataViewSet): class LocationGroupViewSet(MapdataViewSet): - """ Add ?category= to filter by category. """ + """ + Add ?category= to filter by category. + A Location Group is a Location – so if it is visible, you can use its ID in the Location API as well. + """ queryset = LocationGroup.objects.all() class LocationViewSet(RetrieveModelMixin, GenericViewSet): """ - only accesses locations that have can_search or can_describe set to true. + Locations are Levels, Spaces, Areas, POIs and Location Groups (see /locations/types/). They have a shared ID pool. + This API endpoint only accesses locations that have can_search or can_describe set to true. + If you want to access all of them, use the API endpoints for the Location Types. + Additionally, you can access Custom Locations (Coordinates) by using c::x:y as an id or slug. + add ?searchable to only show locations with can_search set to true ordered by relevance add ?detailed to show all attributes add ?geometry to show geometries