Improvements to the guide for using data sources (#37)

Author: joakimnordling

src/routes/guides/images.json

@@ -163,73 +163,73 @@
   },
   "ERROR_RESPONSES": {},
   "PARTY_CONFIGURATION": {},
-  "USING_DATA": {
+  "USING_DATA_SOURCES": {
     "MENU_DATA_SOURCES": {
-      "src": "/guides/using-data-from-data-sources/menu_data_sources.png",
+      "src": "/guides/using-data-sources/menu_data_sources.png",
       "alt": "Menu with arrow pointing at the Data sources section"
     },
     "DATA_SOURCE_SEARCH": {
-      "src": "/guides/using-data-from-data-sources/data_source_search.png",
+      "src": "/guides/using-data-sources/data_source_search.png",
       "alt": "Data sources page showing search field and button to view sources"
     },
     "DATA_SOURCES_FOR_DEFINITION": {
-      "src": "/guides/using-data-from-data-sources/data_sources_for_definition.png",
+      "src": "/guides/using-data-sources/data_sources_for_definition.png",
       "alt": "Listing of sources for a definition with links to resources on the right"
     },
     "DATA_SOURCES_DETAILS": {
-      "src": "/guides/using-data-from-data-sources/data_source_details.png",
+      "src": "/guides/using-data-sources/data_source_details.png",
       "alt": "Details for the data source"
     },
     "MENU_ACCESS_CONTROL_KEYS": {
-      "src": "/guides/using-data-from-data-sources/menu_access_control_keys.png",
+      "src": "/guides/using-data-sources/menu_access_control_keys.png",
       "alt": "Menu with arrow pointing at the Access control keys section"
     },
     "ACCESS_CONTROL_KEYS_LISTING": {
-      "src": "/guides/using-data-from-data-sources/access_control_keys_listing.png",
+      "src": "/guides/using-data-sources/access_control_keys_listing.png",
       "alt": "Listing of access control keys on the Access control keys page"
     },
     "ACCESS_CONTROL_KEYS_VIEW": {
-      "src": "/guides/using-data-from-data-sources/access_control_keys_view.png",
+      "src": "/guides/using-data-sources/access_control_keys_view.png",
       "alt": "Access control keys view for a data source"
     },
     "CURL_EXAMPLE": {
-      "src": "/guides/using-data-from-data-sources/curl_example.png",
+      "src": "/guides/using-data-sources/curl_example.png",
       "alt": "cURL example of requesting an API token using an access control key"
     },
     "CURL_REQUEST": {
-      "src": "/guides/using-data-from-data-sources/curl_request.png",
+      "src": "/guides/using-data-sources/curl_request.png",
       "alt": "Curl request in Swagger UI"
     },
     "GENERATED_API_TOKEN": {
-      "src": "/guides/using-data-from-data-sources/generated_api_token.png",
+      "src": "/guides/using-data-sources/generated_api_token.png",
       "alt": "API token generated with the Generate API token button"
     },
     "ACCESS_CONTROL_KEYS_MAKING_REQUEST": {
-      "src": "/guides/using-data-from-data-sources/access_control_keys_making_request.png",
+      "src": "/guides/using-data-sources/access_control_keys_making_request.png",
       "alt": "Instructions on making request on the Access control keys page"
     },
     "ACCESS_CONTROL_KEYS_LINKS": {
-      "src": "/guides/using-data-from-data-sources/access_control_keys_links.png",
+      "src": "/guides/using-data-sources/access_control_keys_links.png",
       "alt": "Access control keys page with links to Swagger UI and ReDoc"
     },
     "SWAGGER_UI_EXAMPLE_VALUE": {
-      "src": "/guides/using-data-from-data-sources/swagger_ui_example_value.png",
+      "src": "/guides/using-data-sources/swagger_ui_example_value.png",
       "alt": "Swagger UI showing Example Value"
     },
     "SWAGGER_UI_SCHEMA": {
-      "src": "/guides/using-data-from-data-sources/swagger_ui_schema.png",
+      "src": "/guides/using-data-sources/swagger_ui_schema.png",
       "alt": "Swagger UI showing Schema"
     },
     "SWAGGER_UI_TRY_IT_OUT": {
-      "src": "/guides/using-data-from-data-sources/swagger_ui_try_it_out.png",
+      "src": "/guides/using-data-sources/swagger_ui_try_it_out.png",
       "alt": "Swagger UI with Try it out button"
     },
     "SWAGGER_UI_FIELDS": {
-      "src": "/guides/using-data-from-data-sources/swagger_ui_fields.png",
+      "src": "/guides/using-data-sources/swagger_ui_fields.png",
       "alt": "Swagger UI with the necessary fields highlighted"
     },
     "SWAGGER_UI_REQUEST_RESPONSE": {
-      "src": "/guides/using-data-from-data-sources/swagger_ui_request_response.png",
+      "src": "/guides/using-data-sources/swagger_ui_request_response.png",
       "alt": "Swagger UI with the request and response from a source"
     }
   },

src/routes/guides/managing-groups/+page.svelte

@@ -87,6 +87,6 @@
   <ul>
     <li><A href={GUIDES.MANAGE_GROUP_MEMBERS.href}>{GUIDES.MANAGE_GROUP_MEMBERS.title}</A></li>
     <li><A href={GUIDES.BUILD_DATA_SOURCE.href}>{GUIDES.BUILD_DATA_SOURCE.title}</A></li>
-    <li><A href={GUIDES.USING_DATA.href}>{GUIDES.USING_DATA.title}</A></li>
+    <li><A href={GUIDES.USING_DATA_SOURCES.href}>{GUIDES.USING_DATA_SOURCES.title}</A></li>
   </ul>
 </TableOfContents>

src/routes/guides/urls.ts

@@ -19,9 +19,9 @@ export const GUIDES = {
     title: "Verifying API tokens",
     href: "/guides/verifying-api-tokens",
   },
-  USING_DATA: {
-    title: "Using data from data sources",
-    href: "/guides/using-data-from-data-sources",
+  USING_DATA_SOURCES: {
+    title: "Using data sources",
+    href: "/guides/using-data-sources",
   },
   ERROR_RESPONSES: {
     title: "Error responses",

…g-data-from-data-sources/+page.server.ts …uides/using-data-sources/+page.server.tssrc/routes/guides/using-data-from-data-sources/+page.server.ts renamed to src/routes/guides/using-data-sources/+page.server.ts src/routes/guides/using-data-from-data-sources/+page.server.ts renamed to src/routes/guides/using-data-sources/+page.server.ts

@@ -5,7 +5,7 @@ export async function load({ url, route }) {
   return {
     path: url.pathname,
     route: route.id,
-    guide: GUIDES.USING_DATA,
-    images: IMAGES.USING_DATA,
+    guide: GUIDES.USING_DATA_SOURCES,
+    images: IMAGES.USING_DATA_SOURCES,
   }
 }

…sing-data-from-data-sources/+page.svelte …s/guides/using-data-sources/+page.sveltesrc/routes/guides/using-data-from-data-sources/+page.svelte renamed to src/routes/guides/using-data-sources/+page.svelte src/routes/guides/using-data-from-data-sources/+page.svelte renamed to src/routes/guides/using-data-sources/+page.svelte

@@ -21,8 +21,8 @@
   <SectionTitle title="Introduction" />
 
   <p>
-    In this guide we will explain how to find, get access to and use data from data sources
-    published on an IOXIO data sharing service. We will be showing the process on the
+    In this guide we will explain how to find, get access to and use data sources published on an
+    IOXIO data sharing service. We will be showing the process on the
     <A href="https://sandbox.ioxio-dataspace.com/">IOXIO Sandbox Dataspace</A>, but this guide also
     works for most parts on for example
     <A href="https://ioxio.io/">IOXIO.io</A>.
@@ -31,32 +31,31 @@
   <SectionTitle title="Prerequisites" />
 
   <ul>
-    <li>Knowing what kind of data you want to access/use.</li>
+    <li>Knowing what kind of data source you want to access/use.</li>
     <li>
       An account and a group on one of the data sharing services, such as
       <A href="https://sandbox.ioxio-dataspace.com/">IOXIO Sandbox Dataspace</A> or
       <A href="https://ioxio.io/">IOXIO.io</A>.
     </li>
     <li>
-      To access the data, you need to request access for your group. If you don’t yet know which
-      data, you can find instructions to identify the source below, but you cannot connect to it
-      before your group has been granted access.
+      To access the data source, you need to request access for your group. If you don’t yet know
+      which data source, you can find instructions to identify the source below, but you cannot
+      connect to it before your group has been granted access.
     </li>
   </ul>
 
   <SectionTitle title="Finding a data source" />
 
   <p>
-    The first step is to find a data source providing the kind of data you want to use. You can
-    browse all available data sources by going to the <em>Data sources</em>
-    section in the menu.
+    The first step is to find a data source you want to use. You can browse all available data
+    sources by going to the <em>Data sources</em> section in the menu.
   </p>
 
   <GuideImage img={images.MENU_DATA_SOURCES} compact />
 
   <p>
-    Search for the data relevant to you, e.g. using search words, or tags. In this example we’ve
-    searched for data related to <em>weather</em> and will be using a source for the
+    Search for the data sources relevant to you, e.g. using search words, or tags. In this example
+    we’ve searched for data related to <em>weather</em> and will be using a source for the
     <em>Meteorology/Weather</em> definition.
   </p>
 
@@ -139,26 +138,26 @@
     <li>
       <p>
         API tokens: API tokens are short-lived, typically valid for an hour from being generated,
-        and used in the requests to fetch data products from a data source. They are validated by
-        the IOXIO data sharing service (when the <em>Dataspace verified API tokens</em> option is used
-        for the data source) and optionally validated by the data source.
+        and used in the requests to a data source. They are validated by the IOXIO data sharing
+        service (when the <em>Dataspace verified API tokens</em> option is used for the data source)
+        and optionally validated by the data source.
       </p>
       <p>
-        These can be treated as opaque strings for the practical matters of the group requesting
-        data. Technically they are actually JWTs signed by the data sharing service. They prove that
-        the holder of the token, for a limited time, has the right to request data from a particular
-        source on behalf of a the group that generated them. These tokens can not be invalidated or
-        revoked but automatically expire in a short time.
+        These can be treated as opaque strings for the practical matters of the group making the
+        request. Technically they are actually JWTs signed by the data sharing service. They prove
+        that the holder of the token, for a limited time, has the right to make requests to a
+        particular source on behalf of a the group that generated them. These tokens can not be
+        invalidated or revoked but automatically expire in a short time.
       </p>
       <p>
         They are forwarded by the IOXIO data sharing service to the data source so that it can (if
         it wants to) verify that the request came from the IOXIO data sharing service. The data
-        source can also verify which group is requesting data and might also implement its own
+        source can also verify which group is making the request and might also implement its own
         access control to restrict access based on that.
       </p>
       <p>
         API tokens should also be kept safe and only used in server-to-server connections as they
-        can be used to request any data on behalf of the requesting group from the data source.
+        can be used to make any requests on behalf of the group to the data source.
       </p>
     </li>
   </ul>
@@ -238,14 +237,14 @@
   </p>
 
   <p>
-    To make it easier to test fetching data, the access control keys page also has a
+    To make it easier to make test requests the access control keys page also has a
     <em>Generate API token</em> button, that will use one of your access control keys to generate a fresh
     API token that you can easily copy & paste.
   </p>
 
   <GuideImage img={images.GENERATED_API_TOKEN} />
 
-  <SectionTitle title="Requesting data" />
+  <SectionTitle title="Making requests" />
 
   <p>The details page of the access control keys tell you the main parts of making the request:</p>
 
@@ -306,7 +305,7 @@
 
   <GuideImage img={images.SWAGGER_UI_REQUEST_RESPONSE} />
 
-  <p>You should now have successfully requested data from the data source, congratulations!</p>
+  <p>You should now have made a successful request to the data source, congratulations!</p>
 
   <p>
     Below the response you will also find documentation of all the possible responses, incl. errors,
@@ -324,8 +323,8 @@
   </p>
 
   <p>
-    You should also know how to check the details of the definitions to understand what data you
-    need to send and the structure and meaning of the data you are receiving.
+    You should also know how to check the details of the definitions to understand the format of the
+    request and response, as well as the descriptions and meaning of each field in them.
   </p>
 
   <SectionTitle title="Next steps" />