From 8b8d3438643e1f22e7e6b327d811e594865b6edc Mon Sep 17 00:00:00 2001 From: Sam Date: Sun, 14 Jul 2019 16:57:16 +0200 Subject: [PATCH] document first endpoint --- Makefile | 2 +- .../api/{endpoints.rst => activities.rst} | 2 + docs/source/index.rst | 2 +- .../fittrackee_api/activities/activities.py | 138 +++++++++++++++++- 4 files changed, 141 insertions(+), 3 deletions(-) rename docs/source/api/{endpoints.rst => activities.rst} (69%) diff --git a/Makefile b/Makefile index cf36d894..f5bc5706 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ clean-install: rm -fr $(VENV) html: - $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + rm -rf docs/build && $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) install-db: psql -U postgres -f fittrackee_api/db/create.sql diff --git a/docs/source/api/endpoints.rst b/docs/source/api/activities.rst similarity index 69% rename from docs/source/api/endpoints.rst rename to docs/source/api/activities.rst index cbf0ef60..c18caf60 100644 --- a/docs/source/api/endpoints.rst +++ b/docs/source/api/activities.rst @@ -2,3 +2,5 @@ FitTrackee API documentation ############################ .. autoflask:: fittrackee_api:create_app() + :endpoints: + activities.get_activities diff --git a/docs/source/index.rst b/docs/source/index.rst index 53e6838a..9fcfe887 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,7 +10,7 @@ Welcome to FitTrackee's documentation! :maxdepth: 2 :caption: Contents: - api/endpoints + api/activities Indices and tables ================== diff --git a/fittrackee_api/fittrackee_api/activities/activities.py b/fittrackee_api/fittrackee_api/activities/activities.py index dc26e0dd..5bf1e55f 100644 --- a/fittrackee_api/fittrackee_api/activities/activities.py +++ b/fittrackee_api/fittrackee_api/activities/activities.py @@ -23,7 +23,143 @@ activities_blueprint = Blueprint('activities', __name__) @activities_blueprint.route('/activities', methods=['GET']) @authenticate def get_activities(auth_user_id): - """Get all activities for authenticated user""" + """ + Get activities for the authenticated user. + + **Example requests**: + + - minimal request + + .. sourcecode:: http + + GET /api/activities/ HTTP/1.1 + + - with some query parameters + + .. sourcecode:: http + + GET /api/activities?&page=1&per_page=10&from=2019-07-02&to=2019-07-31&sport_id=1 HTTP/1.1 + + **Example responses**: + + - returning at least one activity + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "data": { + "activities": [ + { + "activity_date": "Mon, 01 Jan 2018 00:00:00 GMT", + "ascent": null, + "ave_speed": 10.0, + "bounds": [], + "creation_date": "Sun, 14 Jul 2019 13:51:01 GMT", + "descent": null, + "distance": 10.0, + "duration": "0:17:04", + "id": 1, + "map": null, + "max_alt": null, + "max_speed": 10.0, + "min_alt": null, + "modification_date": null, + "moving": "0:17:04", + "next_activity": 3, + "notes": null, + "pauses": null, + "previous_activity": null, + "records": [ + { + "activity_date": "Mon, 01 Jan 2018 00:00:00 GMT", + "activity_id": 1, + "id": 4, + "record_type": "MS", + "sport_id": 1, + "user_id": 1, + "value": 10.0 + }, + { + "activity_date": "Mon, 01 Jan 2018 00:00:00 GMT", + "activity_id": 1, + "id": 3, + "record_type": "LD", + "sport_id": 1, + "user_id": 1, + "value": "0:17:04" + }, + { + "activity_date": "Mon, 01 Jan 2018 00:00:00 GMT", + "activity_id": 1, + "id": 2, + "record_type": "FD", + "sport_id": 1, + "user_id": 1, + "value": 10.0 + }, + { + "activity_date": "Mon, 01 Jan 2018 00:00:00 GMT", + "activity_id": 1, + "id": 1, + "record_type": "AS", + "sport_id": 1, + "user_id": 1, + "value": 10.0 + } + ], + "segments": [], + "sport_id": 1, + "title": null, + "user_id": 1, + "weather_end": null, + "weather_start": null, + "with_gpx": false + } + ] + }, + "status": "success" + } + + - returning no activities + + .. sourcecode:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "data": { + "activities": [] + }, + "status": "success" + } + + :param integer auth_user_id: authenticate user id + + :query integer page: page if using pagination (default: 1) + :query integer per_page: number of activities returned per page (default: 5) + :query integer sport_id: sport id + :query string from: start date (format: `%Y-%m-%d`) + :query string to: end date (format: `%Y-%m-%d`) + :query float distance_from: minimal distance + :query float distance_to: maximal distance + :query string duration_from: minimal duration (format: `%H:%M`) + :query string duration_to: maximal distance (format: `%H:%M`) + :query float ave_speed_from: minimal average speed + :query float ave_speed_to: maximal average speed + :query float max_speed_from: minimal max. speed + :query float max_speed_to: maximal max. speed + :query string order: sorting order (default: 'desc') + + :reqheader Authorization: OAuth 2.0 Bearer Token + + :statuscode 200: no error + :statuscode 500: + + """ try: user = User.query.filter_by(id=auth_user_id).first() params = request.args.copy()