docs: Apply suggestions from code review

Co-authored-by: Katie Mazaitis <[email protected]>

Author: sgratzl

docs/api/covidcast.md

@@ -92,8 +92,7 @@ sources and signals.
 ## Constructing API Queries
 
 The COVIDcast API is based on HTTP GET queries and returns data in JSON form.
-The base URL is `https://api.covidcast.cmu.edu/epidata/`.  The covidcast
-endpoint is `https://api.covidcast.cmu.edu/epidata/covidcast/`.
+The base URL is `https://api.covidcast.cmu.edu/epidata/covidcast/`.
 
 See [this documentation](README.md) for details on specifying epiweeks, dates,
 and lists.
@@ -185,23 +184,23 @@ API calls.
 
 ### Alternative Response Formats
 
-In addition to the default EpiData Response format, users can customize the response format using the `format=` parameters.
+In addition to the default EpiData Response format, users can customize the response format using the `format=` parameter.
 
 #### JSON List Response
 
-When setting the format parameter to `format=json`, it will return a plain list of the `epidata` response objects without the `result` and `message` wrapper. The status of the query is returned via HTML status codes. For example, a status code of 400 indicates that the request has wrong or missing parameter. The returned value is a JSON message with details.
+When setting the format parameter to `format=json`, it will return a plain list of the `epidata` response objects without the `result` and `message` wrapper. The status of the query is returned via HTTP status codes. For example, a status code of 200 means the query succeeded, while 400 indicates that the query has a missing, misspelled, or otherwise invalid parameter. For all status codes != 200, the returned JSON includes details about what part of the query couldn't be interpreted.
 
 #### CSV File Response
 
-When setting the format parameter to `format=csv`, it will return a CSV file with same columns as the response objects. Similar to the JSON list response status codes are used.
+When setting the format parameter to `format=csv`, it will return a CSV file with same columns as the response objects. HTTP status codes are used to communicate success/failure, similar to `format=json`.
 
 #### JSON New Lines Response
 
 When setting the format parameter to `format=jsonl`, it will return each row as an JSON file separated by a single new line character `\n`. This format is useful for incremental streaming of the results. Similar to the JSON list response status codes are used.
 
 ### Limit Returned Fields
 
-The `fields` parameter can be used to limit the number of returned fields in each returned row. This is useful in web application to reduce the amount of data that is downloaded. The `format` parameter supports two syntaxes. On the one hand, when listing field names only those field names will be returned. For example, `fields=geo_value,value` will return only those selected fields. On the other hand, when listing field names with a preceding dash, it will be interpreted to exclude those fields. For example, `fields=-direction` will not return the `direction` field.
+The `fields` parameter can be used to limit which fields are included in each returned row. This is useful in web applications to reduce the amount of data transmitted. The `fields` parameter supports two syntaxes: allow and deny. Using allowlist syntax, only the listed fields will be returned. For example, `fields=geo_value,value` will drop all fields from the returned data except for `geo_value` and `value`. To use denylist syntax instead, prefix each field name with a dash (-) to exclude it from the results. For example, `fields=-direction` will include all fields in the returned data except for the `direction` field.
 
 
 ## Example URLs

docs/api/covidcast_meta.md

@@ -13,7 +13,7 @@ geographic levels at which they are reported.
 
 ## The API
 
-The base URL is: https://api.covidcast.cmu.edu/epidata/
+The base URL is: https://api.covidcast.cmu.edu/epidata/covidcast_meta/
 
 See [this documentation](README.md) for details on specifying epiweeks, dates, and lists.
 

docs/new_endpoint_tutorial.md

@@ -64,9 +64,9 @@ the following:
 
 # update the server
 
-1. create a new file in `/src/server/endpoints/` e.g., `fluview_meta.py` or copy and existing one.
-2. edit the created file `Blueprint("fluview_meta", __name__)` such that the first argument should match the target endpoint name
-3. edit the existing `/src/server/endpoints/__init__.py`, add the newly created file to the imports at the top and to the list of endpoints below.
+1. create a new file in `/src/server/endpoints/` e.g., `fluview_meta.py`, or copy an existing one.
+2. edit the created file `Blueprint("fluview_meta", __name__)` such that the first argument matches the target endpoint name
+3. edit the existing `/src/server/endpoints/__init__.py` to add the newly-created file to the imports (top) and to the list of endpoints (below).
 
 
 # update the client libraries
@@ -330,7 +330,7 @@ created in this tutorial.
 
 Once it's approved, commit the code. Within a short amount of time (usually ~30
 seconds), the API will begin serving your new endpoint. Go ahead and give it a
-try: https://delphi.midas.cs.cmu.edu/epidata/fluview_meta/
+try: https://delphi.cmu.edu/epidata/fluview_meta/
 
 ```
 {