fix small issues (#33)

* fix forecast params

* fix other problems

* one more link

* moar csv

Author: wholmgren

sfa_api/forecasts.py

@@ -161,7 +161,8 @@ def post(self, forecast_id, *args):
                   to be trusted).
               example: |-
                 timestamp,value,quality_flag
-                2018-10-29T12:04:23Z,32.93,0
+                2018-10-29T12:00:00Z,32.93,0
+                2018-10-29T13:00:00Z,25.17,0
         responses:
           201:
             $ref: '#/components/responses/201-Created'

sfa_api/observations.py

@@ -193,7 +193,8 @@ def post(self, obs_id, *args):
                   to be trusted).
               example: |-
                 timestamp,value,quality_flag
-                2018-10-29T12:04:23Z,32.93,0
+                2018-10-29T12:00:00Z,32.93,0
+                2018-10-29T13:00:00Z,25.17,0
         responses:
           201:
             $ref: '#/components/responses/201-Created'

sfa_api/schema.py

@@ -4,7 +4,7 @@
 from sfa_api import spec, ma
 
 
-VARIABLES = ['ghi', 'dni', 'dhi', 'temp', 'wspd',
+VARIABLES = ['ghi', 'dni', 'dhi', 'temp_air', 'wind_speed',
              'poa', 'ac_power', 'dc_power']
 VARIABLE_FIELD = variable = ma.String(
         title='Variable',
@@ -124,7 +124,7 @@ class Meta:
     variable = VARIABLE_FIELD
     site_id = ma.UUID(
         title='Site ID',
-        description="UUID the assocaiated site",
+        description="UUID the associated site",
         required=True)
     name = ma.String(
         title='Name',
@@ -133,9 +133,10 @@ class Meta:
     interval_label = ma.String(
         title='Interval Label',
         description=('For data that represents intervals, indicates if a time '
-                     'labels the beginning or ending of the interval. N/A for '
-                     'instantaneous data'),
-        validate=validate.OneOf(['start', 'end']))
+                     'labels the beginning or ending of the interval. '
+                     'instant for instantaneous data'),
+        validate=validate.OneOf(['beginning', 'ending', 'instant']),
+        required=True)
     uncertainty = ma.Float(
         title='Uncertainty',
         description='A measure of the uncertainty of the observation values.')
@@ -209,28 +210,27 @@ class Meta:
                      'the run length & issue frequency attribute.'))
     lead_time_to_start = ma.String(
         title='Lead time to start',
-        description="Lead time to start of forecast",
+        description=("The difference between the issue time and the start of "
+                     "the first forecast interval, e.g. 1 hour."),
         required=True)
-
     interval_label = ma.String(
         title='Interval Label',
         description=('For data that represents intervals, indicates if a time '
                      'labels the beginning or ending of the interval. N/A for '
                      'instantaneous data'),
-        validate=validate.OneOf(['start', 'end']))
-    duration = ma.String(
-        title='Duration',
-        description="Interval duration",
-        required=True
-    )
-    intervals = ma.Integer(
-        title='Intervals',
-        description="Intervals per submission",
+        validate=validate.OneOf(['beginning', 'ending', 'instant']))
+    interval_length = ma.String(
+        title='Interval length',
+        description=('The length of time that each data point represents '
+                     'e.g. 5 minutes, 1 hour.'),
         required=True
     )
-    issue_frequency = ma.String(
-        title='Issue Frequency',
-        description="Forecast issue frequency",
+    run_length = ma.String(
+        title='Run Length / Issue Frequency',
+        description=('The total length of a single issued forecast run '
+                     'e.g. 1 hour. To enforce a continuous, non-overlapping '
+                     'sequence, this is equal to the forecast run issue '
+                     'frequency.'),
         required=True,
     )
     value_type = ma.String(

sfa_api/sites.py

@@ -64,7 +64,7 @@ class SiteView(MethodView):
     def get(self, site_id, *args):
         """
         ---
-        summary: Get site information
+        summary: Get site metadata
         tags:
         - Sites
         parameters:
@@ -138,7 +138,7 @@ def get(self, site_id, *args):
         ---
         summary: Get site observations
         description: >
-          Get all observations associated with site that user has access to
+          Get metadata for all observations associated with site that user has access to
         tags:
         - Sites
         parameters:
@@ -167,7 +167,7 @@ def get(self, site_id, *args):
         ---
         summary: Get site forecasts
         description: >
-          Get all forecasts associated with site that user has access to
+          Get metadata for all forecasts associated with site that user has access to
         tags:
         - Sites
         parameters:

sfa_api/spec.py

@@ -43,8 +43,8 @@ def decorator(schema, **kwargs):
         'auth0': {
             'type': 'oauth2',
             'description': """Authorization request must include
-client_id='c16EJo48lbTCQEhqSztGGlmxxxmZ4zX' and
-audience='https://api.solarforecastarbiter.org'""",
+`client_id='c16EJo48lbTCQEhqSztGGlmxxxmZ4zX'` and
+`audience='https://api.solarforecastarbiter.org'`""",
             'flows': {
                 'password': {
                     'tokenUrl': 'https://solarforecastarbiter.auth0.com/oauth/token',  # NOQA
@@ -75,7 +75,7 @@ def decorator(schema, **kwargs):
 observation GET/POST data endpoints which also support CSV files.
 
 Most users will interact with the API indirectly through actions on
-the [dashboard](https://dashboard.solarforecastarbiter.org). Those
+the [dashboard](https://solarforecastarbiter.org/dashboarddoc). Those
 users who require direct access to the API may include observational
 data providers, forecast data providers, and reference data users.
 
@@ -222,9 +222,8 @@ def decorator(schema, **kwargs):
 ```
 
 For more about how to obtain a JWT using the Resource Owner Password flow, see
-https://developer.okta.com/blog/2018/06/29/what-is-the-oauth2-password-grant
-and
-https://auth0.com/docs/api/authentication#resource-owner-password.
+[What is the OAuth2 password grant](https://developer.okta.com/blog/2018/06/29/what-is-the-oauth2-password-grant)
+and [Auth0 Resource Owner Password](https://auth0.com/docs/api/authentication#resource-owner-password).
 """
 ma_plugin = MarshmallowPlugin()
 spec = APISpec(
@@ -259,9 +258,11 @@ def decorator(schema, **kwargs):
         {'name': 'Forecasts',
          'description': 'Access and upload forecast metadata and values.'},
         {'name': 'Reports',
-         'description': 'Access reports.'},
+         'description': 'Access reports. '
+                        'API to be determined in March/April 2019.'},
         {'name': 'Trials',
-         'description': 'Access information about forecast trials.'}
+         'description': 'Access information about forecast trials. '
+                        'API to be determined in March/April 2019.'}
     ],
     servers=[
         {'url': '//dev-api.solarforecastarbiter.org/',