sander/rowsandall
Private
Public Access
1
0
Fork 0
Code Activity

API v2 (version 1)

Browse Source
This commit is contained in:
Sander Roosendaal
2020-07-25 12:26:30 +02:00
parent 37ed947fb7
commit 7fd1b2ba42
4 changed files with 353 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
rowers/templates/developers.html
View File

@@ -10,91 +10,91 @@
<p>On this page, a work in progress, I will collect useful information
for developers of rowing data apps and hardware.</p>
<p>I presume you have an app (smartphone app, dedicated hardware, web site)
where your users (customers) generate, collect or store their rowing
related workout data. You can now offer your users easy ways to get
their data on this site.</p>
</li>
<li class="grid_2">
<li class="grid_4">
<p>There are three ways to allow your users to get data to Rowsandall.com.</p>
<h2>File based export from your app</h2>
<p>Enable export of TCX, FIT or CSV formatted files from your app.
The users
upload the file to Rowsandall.com.</p>
<ul class="contentli">
<p><ul class="contentli">
<li>Advantages
<ul class="contentli">
<p><ul class="contentli">
<li>User sees immediate results</li>
</ul>
</ul></p>
</li>
<li>Disadvantages
<ul class="contentli">
<p><ul class="contentli">
<li>It is a multi-step process: Download from your
app, store, upload.</li>
</ul>
</ul></p>
</li>
</ul>
</ul></p>
<h2>Email from your app</h2>
<p>Similar as above, generate TCX, FIT or CSV formatted files and
email them
to <em>workouts@rowsandall.com</em> directly from your app. The From: field
should be the email address of the registered user.</p>
<ul class="contentli">
<p><ul class="contentli">
<li>Advantages
<ul class="contentli">
<p><ul class="contentli">
<li>It's a simple process, which can be automated.</li>
</ul>
</ul></p>
</li>
<li>Disadvantages
<ul class="contentli">
<p><ul class="contentli">
<li>It may take up to five minutes for the workout to show up
on the site.</li>
</ul>
</ul></p>
</li>
</ul>
</ul></p>
<h2>Using the REST API</h2>
<p>We are building a REST API which will allow you to post and
receive stroke
data from the site directly.</p>
<p>The REST API is a work in progress. We are open to improvement
suggestions (provided they don't break existing apps). Please send
email to <a href="mailto:info@rowsandall.com">info@rowsandall.com</a>
with questions and/or suggestions. We
will get back to you as soon as possible.</p>
<ul class="contentli">
<p><ul class="contentli">
<li>Advantages
<ul class="contentli">
<p><ul class="contentli">
<li>Once it is set up, this is a one-click operation.</li>
<li>You can read a user's workout data from the site and use
them in your app.</li>
<li>This is not limited to workout data. You could make a full mobile
version of our site.</li>
</ul>
</ul></p>
</li>
<li>Disadvantages
<ul class="contentli">
<p><ul class="contentli">
<li>The API is not stable and not fully tested yet.</li>
<li>You need to register your app with us. We can revoke your
permissions if you misuse them.</li>
<li>The user user must grant permissions to your app.</li>
<li>You need to manage authorization tokens.</li>
</ul>
</ul></p>
</li>
</ul>
</ul></p>
</li>
<li class="grid_2">
<li class="grid_4">
<h2>Quick Links</h2>
<h3>Accepted file formats</h3>
@@ -103,20 +103,20 @@
<p>However, some rowing related parameters are not supported by TCX and FIT. Therefore, we are supporting the CSV format that is documented in the following link.</p>
<ul class="contentli"><li><a href="http://rowingdata.readthedocs.io/en/latest/#csv-file-standard">Our standard rowing CSV file</a></li></ul>
<p><ul class="contentli"><li><a href="http://rowingdata.readthedocs.io/en/latest/#csv-file-standard">Our standard rowing CSV file</a></li></ul></p>
<p>Using this standard will guarantee that your user's data are accepted
without complaints.</p>
<h2>API related documentation</h2>
<h3>Registering an app</h3>
<p>We have disabled the self service app link for security reasons.
We will replace it with a secure self service app link soon. If you
need to register an app, please send email to info@rowsandall.com</p>
<h3>Authentication</h3>
<p>Standard <a href="https://oauth.net/2/">Oauth2</a> authentication.
@@ -128,14 +128,15 @@
<p>The redirect URI for user authentication has to be <em>https</em>.
Developers of iOS or Android apps should contact me directly if
this doesn't work for them. I can add exceptions.</p>
<p>
<ul class="contentli">
<li>Authorization URL: <b>https://{{ request.get_host }}/rowers/o/authorize</b></li>
<li>Access Token request: <b>https://{{ request.get_host }}/rowers/o/token/</b></li>
<li>Access Token refresh: <b>https://{{ request.get_host }}/rowers/o/token/</b></li>
<li>Handy utility for testing: <b><a href="http://django-oauth-toolkit.herokuapp.com/consumer/">http://django-oauth-toolkit.herokuapp.com/consumer/</a></b></li>
</ul>
</p>
<h3>API documentation</h3>
@@ -146,12 +147,14 @@
<p>The workout summary data and the stroke data are obtained and sent
separately.</p>
<p>
<ul class="contentli">
<li><a href="/rowers/api-docs/">API documentation</a>
(But refer to the below for stroke data.)</li>
<li><a href="/rowers/api-docs#/workouts">Try out the workout summary API</a></li>
<li><a href="/rowers/api-docs#!/workouts/strokedata_list">GET stroke data</a></li>
</ul>
</p>
<h3>POST stroke data - API</h3>
<p>You can only post stroke data to an existing workout with
workout number {id}. If the workout already has stroke data, you
@@ -159,9 +162,13 @@
future to enable updating stroke data. Stroke data for workout {id} are
posted to:</p>
<h4>API v1</h4>
<p>
<ul class="contentli">
<li><b>https://{{ request.get_host }}/rowers/api/workouts/{id}/strokedata</b></li>
</ul>
</p>
<p>The payload is application/json data and looks as follows:</p>
@@ -176,14 +183,48 @@
}
</pre></p>
<p>Mandatory data fields are:</p>
<h4>API v2</h4>
<p>
<ul class="contentli">
<li><b>https://{{ request.get_host }}/rowers/api/v2/workouts/{id}/strokedata</b></li>
</ul>
</p>
<p>The payload is application/json data and looks as follows:</p>
<p><pre>
{'data':
[
{"distance":5, "power": 112, "hr": 132, "pace": 145800, "spm": 11, "time": 0},
{"distance":12, "power": 221, "hr": 131, "pace": 116400, "spm": 41, "time": 2200},
{"distance":19, "power": 511, "hr": 131, "pace": 88100, "spm": 56, "time": 4599},
{"distance":27, "power": 673, "hr": 132, "pace": 80400, "spm": 59, "time": 7000},
{"distance":35, "power": 744, "hr": 133, "pace": 77700, "spm": 55, "time": 9599},
{"distance":43, "power": 754, "hr": 136, "pace": 77400, "spm": 48, "time": 12000},
{"distance":51, "power": 754, "hr": 139, "pace": 77400, "spm": 48, "time": 14400},
{"distance":59, "power": 749, "hr": 142, "pace": 77600, "spm": 48, "time": 16799},
{"distance":67, "power": 729, "hr": 145, "pace": 78300, "spm": 48, "time": 19400},
{"distance":75, "power": 729, "hr": 147, "pace": 78300, "spm": 48, "time": 21799},
{"distance":82, "power": 726, "hr": 150, "pace": 78400, "spm": 48, "time": 24200},
{"distance":90, "power": 709, "hr": 152, "pace": 79000, "spm": 48, "time": 26599},
{"distance":100, "power": 707, "hr": 153, "pace": 79100, "spm": 49, "time": 29000},
]
}
</pre></p>
<p>For both v1 and v2, mandatory data fields are:</p>
<p>
<ul class="contentli">
<li><b>time</b>: Time (milliseconds since workout start)</li>
<li><b>distance</b>: Distance (meters)</li>
<li><b>pace</b>: Pace (milliseconds per 500m)</li>
<li><b>spm</b> Stroke rate (strokes per minute)</li>
</ul>
</p>
<p>Optional data fiels are:</p>
<p>
<ul class="contentli">
<li><b>power</b>: Power (Watt)</li>
<li><b>drivelength</b>: Drive length (meters)</li>
@@ -201,13 +242,13 @@
<li><b>slip</b>: Slip as defined per Empower oarlock (degrees)</li>
</ul>
<p>Consistency checks will be done and the stroke data will be
</p>
<p>For both API versions, consistency checks will be done and the stroke data will be
refused if the mandatory data fields don't pass the checks.
All mandatory data fields
must have the same number of records. If an optional data field
fails a test, its values are silently replaced by zeros.</p>
</li>
</ul>
@@ -216,4 +257,3 @@
{% block sidebar %}
{% include 'menu_help.html' %}
{% endblock %}