Clarify user_id, add relation types for registration, password recove…

…ry and other user account related tasks #404
Open-EO · Jul 27, 2021 · b5a73fc · b5a73fc
1 parent 07117cc
commit b5a73fc
Show file tree

Hide file tree

Showing 2 changed files with 49 additions and 14 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `GET /jobs/{job_id}/results`: Recommendation to add a link with relation type `canonical` which points to a signed URL with the same content as the response. [#397](https://github.com/Open-EO/openeo-api/issues/397)
+- `GET /`: New Relation types: [#404](https://github.com/Open-EO/openeo-api/issues/404)
+  - `create-form` to link to the registration page
+  - `recovery-form` to link to the credentials recovery page.
+- `GET /me`: New Relation types `alternate` and `related` for user-specific external pages. [#404](https://github.com/Open-EO/openeo-api/issues/404)
+- Recommendation to add media types and titles to links for a better user experience.
 
 ### Changed
 
@@ -19,6 +24,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed inconsistencies in errors.json: removed `ProcessGraphIdDoesntMatch`, clarified `ProcessGraphMissing`, added `ProcessInvalid` and `ProcessGraphInvalid`. [#394](https://github.com/Open-EO/openeo-api/issues/394), [#395](https://github.com/Open-EO/openeo-api/issues/395), [#401](https://github.com/Open-EO/openeo-api/issues/401)
 - Fixed the default value for the version number in the API url (`v1.0` -> `v1`) and improved the description for API versioning. [#393](https://github.com/Open-EO/openeo-api/issues/393)
 - Fixed the Collection example to use `gsd` instead of `eo:gsd`. [#399](https://github.com/Open-EO/openeo-api/issues/399)
+- Clarify use of `user_id`. [#404](https://github.com/Open-EO/openeo-api/issues/404)
+- Clarify that the relation type `version-history` should include `/.well-known/openeo` in the URL.
 
 ## [1.1.0] - 2021-05-17
 

diff --git a/openapi.yaml b/openapi.yaml
@@ -46,6 +46,8 @@ info:
 
     3. `about`: A resource that is related or further explains the resource, e.g. a user guide.
 
+    Generally, it is RECOMMENDED to add descriptive titles (propertty `title`) and media type information (propertty `type`) for a better user experience.
+
     ## Error Handling
 
     The success of requests MUST be indicated using [HTTP status codes](https://www.rfc-editor.org/rfc/rfc7231.html#section-6) according to [RFC 7231](https://www.rfc-editor.org/rfc/rfc7231.html).
@@ -472,7 +474,7 @@ tags:
 
       Therefore, the API leaves some aspects open that have to be handled by the back-ends separately, including 
 
-      * credential recovery, e.g. retrieving a forgotten password
+      * credentials recovery, e.g. retrieving a forgotten password
       * user data management, e.g. changing the users payment details or email address
       * payments, i.e. topping up credits for pre-paid services or paying for post-paid services
       * other accounting related tasks, e.g. creating invoices,
@@ -793,8 +795,8 @@ paths:
                       following `rel` (relation) types:
 
                       1. `version-history`: A link back to the Well-Known URL
-                      (see `/.well-known/openeo`) to allow clients to work on
-                      the most recent version.
+                      (including `/.well-known/openeo`, see the corresponding endpoint for details)
+                      to allow clients to work on the most recent version.
 
                       2. `terms-of-service`: A link to the terms of service. If
                       a back-end provides a link to the terms of service, the
@@ -824,6 +826,12 @@ paths:
                       6. `data`: A link to the collections (see `/collections`).
                       Required if full OGC API compatibility is desired.
 
+                      7. `create-form`: A link to a user registration page.
+
+                      8. `recovery-form`: A link to a page where a user can
+                      recover a user account (e.g. to reset the password or send
+                      a reminder about the username to the user's email account).
+
                       For additional relation types see also the lists of
                       [common relation types in openEO](#section/API-Principles/Web-Linking).
                     type: array
@@ -842,6 +850,14 @@ paths:
                         rel: privacy-policy
                         type: text/html
                         title: Privacy Policy
+                      - href: 'https://www.cool-cloud-corp.com/register'
+                        rel: create-form
+                        type: text/html
+                        title: User Registration
+                      - href: 'https://www.cool-cloud-corp.com/lost-password'
+                        rel: recovery-form
+                        type: text/html
+                        title: Reset Password
                       - href: 'http://www.cool-cloud-corp.com/.well-known/openeo'
                         rel: version-history
                         type: application/json
@@ -3437,7 +3453,13 @@ paths:
                   - user_id
                 properties:
                   user_id:
-                    $ref: '#/components/schemas/user_id'
+                    type: string
+                    description: >-
+                      A unique user identifier specific to the back-end, which could either be chosen by a user or is automatically generated by the back-end during the registration process at the back-end.
+
+                      It is meant to be used as an identifier in URIs (e.g. for sharing purposes), which is primarily used in machine-to-machine communication. Preferrably use the human-readable property `name` to display the user's name in user interfaces instead of the user identifier.
+                    pattern: '^[\w\-\.~]+$'
+                    example: john_doe
                   name:
                     type: string
                     description: >-
@@ -3490,6 +3512,14 @@ paths:
 
                       2. `edit-form`: Points to a page where the user can edit his user profile.
 
+                      3. `alternate`: Any other representation of these (and potentially additional)
+                      user information, e.g. the (public) user profile page.
+                      It is RECOMMENDED to add descriptive titles for a better user experience.
+
+                      4. `related`: Any other user-specific links to be shown in clients,
+                      e.g. to user-specific settings, invoices, etc. It is RECOMMENDED to 
+                      add descriptive titles for a better user experience.
+
                       For additional relation types see also the lists of
                       [common relation types in openEO](#section/API-Principles/Web-Linking).
                     type: array
@@ -3508,6 +3538,10 @@ paths:
                         rel: alternate
                         type: text/vcard
                         title: vCard of John Doe
+                      - href: 'https://example.openeo.org/john_doe/invoices'
+                        rel: related
+                        type: text/html
+                        title: Invoices
         4XX:
           $ref: '#/components/responses/client_error_auth'
         5XX:
@@ -3549,7 +3583,8 @@ components:
             the following `rel` (relation) types:
 
             1. `about`: A resource that further explains the runtime,
-            e.g. a user guide or the documentation.
+            e.g. a user guide or the documentation. It is RECOMMENDED to 
+            add descriptive titles for a better user experience.
 
             For additional relation types see also the lists of
             [common relation types in openEO](#section/API-Principles/Web-Linking).
@@ -3614,7 +3649,8 @@ components:
                             the following `rel` (relation) types:
 
                             1. `about`: A resource that further explains the library,
-                            e.g. a user guide or the documentation.
+                            e.g. a user guide or the documentation. It is RECOMMENDED to 
+                            add descriptive titles for a better user experience.
 
                             2. `latest-version`: If a library has been marked as deprecated,
                             a link SHOULD point to either a new library replacing the deprecated
@@ -5314,14 +5350,6 @@ components:
         Date and time of the last status change, formatted as a [RFC
         3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time.
       example: '2017-01-01T09:36:18Z'
-    user_id:
-      type: string
-      description: >-
-        Unique identifier of the user. MUST match the specified pattern.
-        This is usually a randomly generated internal identifier from the provider
-        not meant for displaying purposes.
-      pattern: '^[\w\-\.~]+$'
-      example: john_doe
     description:
       type: string
       format: commonmark