[BACK-3857] Add API docs for user consent records #165

toddkazakov · 2025-07-21T06:28:53Z

No description provided.

github-actions · 2025-07-21T06:32:26Z

PR Preview Action v1.6.2
🚀 View preview at https://developer.tidepool.org/TidepoolApi/pr-preview/pr-165/
Built to branch `gh-pages` at 2025-08-20 12:01 UTC. Preview will be ready when the GitHub Pages deployment is complete.

tjotala · 2025-07-21T15:37:26Z

reference/auth/models/consent/consent.v1.yaml

+properties:
+  type:
+    description: Test
+    type: string


Consider externalizing this to a separate model that can be re-used in the URL paths and here as well.

Since this is basically an enum, consider also adding a regex pattern of allowable characters and/or min/max length.

tjotala · 2025-07-21T15:38:13Z

reference/auth.v1.yaml

+    parameters: []
+  '/v1/consents/{type}':
+    parameters:
+      - schema:


Consider externalizing this as it's shared by many of the APIs

tjotala · 2025-07-21T15:38:40Z

reference/auth.v1.yaml

+            application/json:
+              schema:
+                $ref: ./auth/models/consent/consents.v1.yaml
+      operationId: GetConentVersions


tjotala · 2025-07-21T15:40:23Z

reference/auth.v1.yaml

+      description: Returns a list of all consent versions for a given type
+  '/v1/users/{userId}/consents':
+    parameters:
+      - schema:


$ref: './common/models/tidepooluserid.yaml'

tjotala · 2025-07-21T15:43:37Z

reference/auth/models/consent/consentrecord.v1.yaml

Should there be something here? Or is this now record.v1.yaml?

It was renamed to record.v1.yaml

tjotala · 2025-07-21T15:45:29Z

reference/auth/models/consent/consents.v1.yaml

+    x-stoplight:
+      id: iepviv3jm8m9m
+    type: array
+    items:


uniqueItems: true?

tjotala · 2025-07-21T15:51:23Z

reference/auth/models/consent/metadata.v1.yaml

+        id: iew30v83r2ce5
+      type: string
+      enum:
+        - ADCES Foundation


Is the intent here that the UX could use these enums directly as human-readable strings? Do we envision them ever to be localizable?

What should happen if the org changes their displayable name (e.g. JDRF -> Breakthrough T1D), or an org gets removed? This has happened at least 3 times thus far (https://tidepool.atlassian.net/browse/WEB-736, https://tidepool.atlassian.net/browse/WEB-3447, https://tidepool.atlassian.net/browse/WEB-824)

This enum represents all valid values that are accepted and returned in API requests. If we rename an organization, we ought to migrate all records. It's the responsibility of the frontend to maintain a list of all valid organizations for initial selection.

tjotala · 2025-07-21T15:52:40Z

reference/auth/models/consent/record.v1.yaml

+type: object
+properties:
+  id:
+    type: string


Since this type is referenced as a URL path component, it'd be good to define as a separate model, re-usable in both places.

tjotala · 2025-07-21T15:53:40Z

reference/auth/models/consent/records.v1.yaml

+type: object
+properties:
+  data:
+    type: array


uniqueItems: true?

tjotala · 2025-07-21T15:55:41Z

reference/auth/models/consent/recordupdate.v1.yaml

+x-stoplight:
+  id: c8oq1dn4m4uak
+type: object
+properties:


Should this include metadata as well? Otherwise, how will one update their supportedOrganizations?

If so, then the required properties could be either status or metadata - or maybe we need an explicit API for revocation, and another for updating metadata.

Good point. Need to think about this.

Metadata is the only updatable attribute now. Consent can be revoked by sending a DELETE request.

tjotala · 2025-07-21T15:58:14Z

reference/auth/models/consent/metadata.v1.yaml

+  id: 8ctwq6xjg496g
+type: object
+properties:
+  supportedOrganizations:


Do we envision other types of consents having attached metadata?

If so, consider making this specific to TBDDP, and perhaps define a top-level metadata that uses it as oneOf, keyed on type.

tjotala · 2025-07-21T16:02:27Z

reference/auth/models/consent/consent.v1.yaml

+    description: Test
+    type: string
+  version:
+    type: integer


Suggest checking with Jake on whether we can rely on this version being a simple integer. We may need to accommodate an arbitrary string.

I can see the value of an integer version for sorting, but we could accomplish that using createdTime as well?

Talked to Jake - using an integer is ok

tjotala · 2025-07-21T16:04:33Z

reference/auth.v1.yaml

+              schema:
+                $ref: ./auth/models/consent/consents.v1.yaml
+      operationId: ListConsents
+      description: Retrieves the list of all different consent types and their content. By default returns only the latest version for each consent type. This can be override by setting the `version` query parameter to `all`


Are these returned in any predictable / stable sort order (e.g. version or createdTime)?

Related question: is the latest by the version or by the createdTime? Is it possible for a lower version to have a later createdTime?

By version. createdTime and modifiedTime are only added for consistency and easier data syncs.

tjotala · 2025-07-21T16:18:15Z

reference/auth.v1.yaml

@@ -680,6 +680,159 @@ paths:
        - sessionToken: []
      tags:
        - Internal
+  /v1/consents:
+    get:


Do we need to be able to restrict the list of consent types that could be accepted by a user? Or can everyone consent to everything? Put another way: does this API require a valid access token?

I could see a potential use-case for restricting this due to kind of an invitation-only or restricted clinical trial. However, this creates a problem with defining who can see which consent types, and how does that work with people who do not yet have a user account. Similar to invitation workflows.

Suggest checking in with Jake and Product team for this.

The list endpoint is for internal/admin use only. We could make this endpoint public and add restrictions in the future. The frontend should be responsible for fetching a particular consent by type so it can be rendered.

tjotala · 2025-07-21T16:33:49Z

reference/auth.v1.yaml

+          in: query
+          name: type
+    post:
+      summary: Create User Consent Record


Can a user grant consent only the latest version of a consent? What happens if they try to grant consent to older version?
Can a user grant consent to something they already consented to (i.e. duplicate record)?

This may need a bit more description of the various workflows - are these correct interpretations of the proposed API?

Granting consent for the first time: CreateUserConsentRecord with latest version

Updating a consent to agree to a new version: CreateUserConsentRecord with a newer latest version

Updating a consent with new metadata: UpdateUserConsentRecord with new metadata only

Updating a consent to revoke it: UpdateUserConsentRecord with status = revoked only

Yes

Yes, but it revokes previous consents for the same type

Need to think some more about the metadata

Yes

Added DELETE /v1/users/{userId}/consents/{recordId} for 4. (revoking a consent record)

I wonder if by definition any new version of consent in case #2 is a superset of the original consent? If we revoke the past consent, does that mean we need to purge content they shared while that previous consent was in effect?

IANAL so might be best to check with Jake.

How we interpret revocation dates and whether we purge the data depends on the type of the consent and the actual content. Currently, I believe we state that date shared with BDDP accounts is not purged even after the consent is revoked.

ewollesen · 2025-08-14T19:12:42Z

reference/auth.v1.yaml

+                $ref: ./auth/models/consent/consent.v1.yaml
+      operationId: GetLatestConsentByType
+      description: Returns the latest consent version for the given type
+  '/v1/consent/{consentType}/versions':


Nit pick, but now is the time...

Usually these endpoints use a plural form, like /users even if we're retrieving something for only a single user. Or like the /users/{userid}/consents endpoint that you add later in this doc.

I'm fine either way, I don't think it's a big deal, but if you wanted to maintain more consistency, you might consider the change.

Suggested change

'/v1/consent/{consentType}/versions':

'/v1/consents/{consentType}/versions':

ewollesen · 2025-08-14T19:19:37Z

reference/auth.v1.yaml

+  '/v1/users/{userId}/consents/{recordId}':
+    parameters:
+      - $ref: '#/components/parameters/userId'
+      - schema:


I feel like this should be better specified as either a UUID or a mongo objectid or... something?

Consider adding at least a max length here? Even just something like 1024.

ewollesen · 2025-08-14T19:24:55Z

reference/auth.v1.yaml

+      description: Retrieves a consent record by ID for a given user.
+    patch:
+      summary: Update User Consent Record
+      operationId: UpdateUserConsentRecord


In most places we use Update<X> with PUT requests, which may or may not obey PUT semantics. Now we're adding PATCH endpoints called Update<X> (which will hopefully only implement PATCH semantics). I'm worried this will get confusing when implementing the handler functions.

Ideally (IMO), PATCH => Update<X> and PUT => Replace<X>, but that's too big of a change for no really good reason.

Is it clearer if we have PATCH => Patch<X> or just something other than Update<X>, so it's clear what the handler's expected semantics are?

Mostly just thinking out loud here, I don't think I feel strongly enough to ask for anything here to be changed. Do you have thoughts?

To summarize, I would like it if I knew that a handler named Update<X> was supposed to behave in a certain way, and if we have PUT Update<X> that does multiple different things already (some obey traditional PUT some don't), and then we add PATCH Update<X> it just all becomes more confusing than it needs to be.

ewollesen · 2025-08-14T19:33:26Z

reference/auth/models/consent/record.v1.yaml

+    type: string
+    minLength: 1
+    readOnly: true
+  status:


Rather than having a grab bag status field, which can be abused in future changes to the model, consider simply having a "revoked" field that's a timestamp. If the timestamp is a non-zero value, then it has been revoked.

ewollesen · 2025-08-14T19:35:45Z

reference/auth/models/consent/record.v1.yaml

+    x-stoplight:
+      id: s4pt6ptt7ez4n
+    minimum: 1
+  grantTime:


Rather than repeating Time in each of these fields, consider just naming them granted, revoked, created, and updated. The time is specified in the type of the field, so there's no need to repeat it in the field's name.

Is grantTime useful?

Assuming that revocationTime is non-zero (or the status == granted, but I'd remove the status field, personally), then I can assume it's been granted. Specifically at the createdTime, right?

The Time suffix is consistent with the rest of the platform services. Same goes with createdTime and updatedTime. It makes querying the database a little easier.

I think both grant time and status are useful for downstream consumers because it takes off the responsibility from explaining the implied meaning of the fields of the model. This will be useful to the data science team.

ewollesen · 2025-08-14T19:51:08Z

reference/auth.v1.yaml

+              schema:
+                $ref: ./auth/models/consent/consents.v1.yaml
+      operationId: GetConsentVersions
+      description: Returns a list of all consent versions for a given type


Do we need this endpoint? Given that version is an integer, it feels safe to assume that if the latest version is 4, then the list of versions is 4, 3, 2, and 1, right?

If the latest version of a consent is 5, can a user consent to version 3? I think the API as it is right now would allow this, but why should the system allow that?

Passing a version with a CreateRecord request makes sense, so we can double check that if they're creating a record for version 4, but version 5 is the newest, we can refuse and return an error. Is there some reason I don't understand for letting someone consent to an older version?

This endpoint is only for admin purposes. I believe it will be useful down the road to display all consents versions of a given type e.g. in Orca.

ewollesen · 2025-08-14T20:05:40Z

reference/auth.v1.yaml

+      parameters:
+        - schema:
+            type: string
+            enum:


What other values would ever be added to this enum? Would this be better as a boolean flag? That is, ?allVersions=true

This was changed to latest=true but that change was not published to GH, apologies.

ewollesen · 2025-08-14T20:09:43Z

reference/auth/models/consent/records.v1.yaml

+      $ref: ./record.v1.yaml
+      x-stoplight:
+        id: u1b4u8fpl1ed6
+  count:


Is this useful? Isn't it just a data.length? Do we really need to put this in the response when it's so easy for a client to calculate it itself?

PS- I believe a count appears in the list of consent types too.

This is not the length of the data array. Count is the total number of documents matching the query.

ewollesen · 2025-08-14T20:20:04Z

reference/auth/models/consent/consents.v1.yaml

+  id: o02joytb2fxay
+type: object
+properties:
+  data:


Suggested change

data:

consents:

ewollesen · 2025-08-14T20:20:39Z

reference/auth/models/consent/record.v1.yaml

+type: object
+properties:
+  id:
+    type: string


ginnyyadav · 2025-09-03T18:12:15Z

reference/auth/models/consent/record.v1.yaml

+    enum:
+      - <12
+      - 13-17
+      - 18+


Looks like the API actually expects "<13", "13-17", ">=18"

ginnyyadav · 2025-09-04T18:47:15Z

reference/auth.v1.yaml

+          content:
+            application/json:
+              schema:
+                $ref: ./auth/models/consent/consent.v1.yaml


GET /v1/consents/big_data_donation_project results in this response:

{
"data": [
{
"type": "big_data_donation_project",
"version": 1,
"content": "### Tidepool Big Data Donation Project ....",
"contentType": "markdown",
"createdTime": "2025-09-03T15:46:08.398Z"
}
],
"count": 1
}

which is not a single object as referenced here, but an array of objects. we should return the latest consent object directly I think or switch to the consents model (though the latter makes less sense for what I think this endpoint is intended for)

ginnyyadav · 2025-09-04T19:25:50Z

reference/auth.v1.yaml

+      - $ref: '#/components/parameters/userId'
+    get:
+      summary: Get User Consent Records
+      tags: []


add Consent tag

ginnyyadav · 2025-09-04T19:26:29Z

reference/auth.v1.yaml

+      - $ref: '#/components/parameters/recordId'
+    get:
+      summary: Get User Consent Record
+      tags: []


Add Consent tag

The rest of the requests also don't have consent tags so they're popped out of the consent folder. I would add those too if you want them all under the "Consent" folder in the API docs.

ginnyyadav · 2025-09-04T19:31:51Z

reference/auth.v1.yaml

+    get:
+      summary: Get Latest Consent By Type
+      tags:
+        - Consent


for this and all of these requests below we should add

security:
- sessionToken: []

as we have done in the rest of the docs.

edit: For this particular one /v1/consents ooks like the security there might be a server token but the rest seem to work with a session token

edit 2: Somehow the sessionToken authorization is indeed showing up on redocly. Either sorcery or I'm looking at something outdated? You may be able to disregard this...

There's likely a global security setting. Added it explicitly.

ginnyyadav · 2025-09-04T20:02:43Z

reference/auth.v1.yaml

+          content:
+            application/json:
+              schema:
+                $ref: ./auth/models/consent/record.v1.yaml


'403': description: Forbidden content: application/json: schema: $ref: ./common/models/error.v1.yaml ect ect....

ginnyyadav · 2025-09-05T16:59:56Z

reference/auth.v1.yaml

+      description: 'Retrieves the list of all different consent types and their content. '
+      requestBody:
+        content: {}
+      parameters: []


looks like type is indeed a parameter.

also type and latest together can be used but not latest by itself

also page (integer)

also size (integer)

and type and version

ginnyyadav · 2025-09-05T19:09:45Z

reference/auth/models/consent/record.v1.yaml

+      id: r7ypd0pfkbhkv
+    format: date-time
+    readOnly: true
+  updatedTime:


did updatedTime change to modifiedTime?

current response looks like this:

{
"id": "53b6f61168ea8914fe0a83c417e3f033",
"userId": "fbfb1adf-4bba-47a2-850d-285cd23ad644",
"status": "active",
"ageGroup": "<13",
"ownerName": "Mufasa Lion",
"parentGuardianName": "Ahadi Lion",
"grantorType": "parent/guardian",
"type": "big_data_donation_project",
"version": 1,
"metadata": {
"supportedOrganizations": []
},
"grantTime": "2025-09-04T17:58:29.787Z",
"createdTime": "2025-09-04T17:58:29.787Z",
"modifiedTime": "2025-09-04T17:58:29.795Z"
}

there is also a userId being sent back as well

modifiedTime is correct and consistent with the rest of the platform models

Add API docs for user consent records

411836d

toddkazakov force-pushed the tk-user-consent branch from d41c0df to 411836d Compare July 21, 2025 06:42

tjotala reviewed Jul 21, 2025

View reviewed changes

Address code review feedback

18a6e35

ewollesen reviewed Aug 14, 2025

View reviewed changes

Address code review comments

31640b6

toddkazakov force-pushed the tk-user-consent branch from 53b9445 to 31640b6 Compare August 15, 2025 08:39

Update response codes

f925a5d

toddkazakov requested a review from ewollesen August 20, 2025 11:58

ewollesen approved these changes Aug 21, 2025

View reviewed changes

ginnyyadav reviewed Sep 3, 2025

View reviewed changes

ginnyyadav reviewed Sep 4, 2025

View reviewed changes

reference/auth.v1.yaml

- $ref: '#/components/parameters/userId'

get:

summary: Get User Consent Records

tags: []

Copy link

Member

ginnyyadav Sep 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add Consent tag

ginnyyadav reviewed Sep 4, 2025

View reviewed changes

ginnyyadav reviewed Sep 5, 2025

View reviewed changes

	'/v1/consent/{consentType}/versions':
	'/v1/consents/{consentType}/versions':

Uh oh!

[BACK-3857] Add API docs for user consent records #165

Are you sure you want to change the base?

[BACK-3857] Add API docs for user consent records #165

Uh oh!

Conversation

toddkazakov commented Jul 21, 2025

Uh oh!

github-actions bot commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2025-08-20 12:01 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

toddkazakov Jul 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jul 21, 2025 •

edited

Loading

Built to branch `gh-pages` at 2025-08-20 12:01 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

toddkazakov Jul 30, 2025 •

edited

Loading