Skip to content

Commit 9b28dc7

Browse files
technicallyjoshtechnicallyjosh
authored
Improve some API docs and add members fields (#22237)
<!--Delete sections as needed --> ## Description - Adds missing information for org members calls. - Improves some areas of the docs. ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [x] Technical review - [x] Editorial review - [ ] Product review
1 parent 33bccdc commit 9b28dc7

File tree

1 file changed

+135
-105
lines changed

1 file changed

+135
-105
lines changed

‎content/reference/api/hub/latest.yaml‎

Lines changed: 135 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ tags:
113113
description: |
114114
The Audit Logs API endpoints allow you to query audit log events across a namespace.
115115
116-
For more information, see [Audit Log](https://docs.docker.com/admin/organization/activity-logs/).
116+
For more information, see [Audit Logs](https://docs.docker.com/admin/organization/activity-logs/).
117117
- name: org-settings
118118
x-displayName: Org Settings
119119
description: |
@@ -272,7 +272,7 @@ paths:
272272
$ref: '#/components/responses/unauthorized'
273273
/v2/access-tokens:
274274
post:
275-
summary: Create a personal access token
275+
summary: Create personal access token
276276
description: Creates and returns a personal access token.
277277
tags:
278278
- access-tokens
@@ -296,7 +296,7 @@ paths:
296296
'401':
297297
$ref: '#/components/responses/Unauthorized'
298298
get:
299-
summary: Get a list of personal access tokens
299+
summary: List personal access tokens
300300
description: Returns a paginated list of personal access tokens.
301301
tags:
302302
- access-tokens
@@ -332,7 +332,7 @@ paths:
332332
schema:
333333
type: string
334334
patch:
335-
summary: Update a personal access token
335+
summary: Update personal access token
336336
description: |
337337
Updates a personal access token partially. You can either update the token's label or enable/disable it.
338338
tags:
@@ -357,7 +357,7 @@ paths:
357357
'401':
358358
$ref: '#/components/responses/Unauthorized'
359359
get:
360-
summary: Get a personal access token
360+
summary: Get personal access token
361361
description: Returns a personal access token by UUID.
362362
tags:
363363
- access-tokens
@@ -381,7 +381,7 @@ paths:
381381
'404':
382382
$ref: '#/components/responses/NotFound'
383383
delete:
384-
summary: Delete a personal access token
384+
summary: Delete personal access token
385385
description: |
386386
Deletes a personal access token permanently. This cannot be undone.
387387
tags:
@@ -395,11 +395,102 @@ paths:
395395
$ref: '#/components/responses/Unauthorized'
396396
'404':
397397
$ref: '#/components/responses/NotFound'
398+
/v2/auditlogs/{account}/actions:
399+
get:
400+
summary: List audit log actions
401+
description: |
402+
List audit log actions for a namespace to be used as a filter for querying audit log events.
403+
operationId: AuditLogs_ListAuditActions
404+
security:
405+
- bearerAuth: []
406+
responses:
407+
'200':
408+
description: A successful response.
409+
content:
410+
application/json:
411+
schema:
412+
$ref: '#/components/schemas/GetAuditActionsResponse'
413+
examples:
414+
response:
415+
value:
416+
actions:
417+
org:
418+
actions:
419+
- name: team.create
420+
description: contains team create events
421+
label: Team Created
422+
- name: team.delete
423+
description: contains team delete events
424+
label: Team Deleted
425+
- name: team.member.add
426+
description: contains team member add events
427+
label: Team Member Added
428+
- name: team.member.remove
429+
description: contains team member remove events
430+
label: Team Member Removed
431+
- name: team.member.invite
432+
description: contains team member invite events
433+
label: Team Member Invited
434+
- name: member.removed
435+
description: contains org member remove events
436+
label: Organization Member Removed
437+
- name: create
438+
description: contains organization create events
439+
label: Organization Created
440+
label: Organization
441+
repo:
442+
actions:
443+
- name: create
444+
description: contains repository create events
445+
label: Repository Created
446+
- name: delete
447+
description: contains repository delete events
448+
label: Repository Deleted
449+
- name: change_privacy
450+
description: contains repository privacy change events
451+
label: Privacy Changed
452+
- name: tag.push
453+
description: contains image tag push events
454+
label: Tag Pushed
455+
- name: tag.delete
456+
description: contains image tag delete events
457+
label: Tag Deleted
458+
label: Repository
459+
'429':
460+
description: ''
461+
content:
462+
application/json:
463+
schema: {}
464+
examples:
465+
response:
466+
value:
467+
detail: Rate limit exceeded
468+
error: false
469+
'500':
470+
description: ''
471+
content:
472+
application/json:
473+
schema: {}
474+
default:
475+
description: An unexpected error response.
476+
content:
477+
application/json:
478+
schema:
479+
$ref: '#/components/schemas/rpcStatus'
480+
parameters:
481+
- name: account
482+
description: Namespace to query audit log actions for.
483+
in: path
484+
required: true
485+
schema:
486+
type: string
487+
tags:
488+
- audit-logs
398489
/v2/auditlogs/{account}:
399490
get:
400-
summary: Returns list of audit log events
401-
description: Get audit log events for a given namespace.
402-
operationId: AuditLogs_GetAuditLogs
491+
summary: List audit log events
492+
description: List audit log events for a given namespace.
493+
operationId: AuditLogs_ListAuditLogs
403494
security:
404495
- bearerAuth: []
405496
responses:
@@ -504,97 +595,6 @@ paths:
504595
default: 25
505596
tags:
506597
- audit-logs
507-
/v2/auditlogs/{account}/actions:
508-
get:
509-
summary: Returns list of audit log actions
510-
description: |
511-
Get audit log actions for a namespace to be used as a filter for querying audit events.
512-
operationId: AuditLogs_GetAuditActions
513-
security:
514-
- bearerAuth: []
515-
responses:
516-
'200':
517-
description: A successful response.
518-
content:
519-
application/json:
520-
schema:
521-
$ref: '#/components/schemas/GetAuditActionsResponse'
522-
examples:
523-
response:
524-
value:
525-
actions:
526-
org:
527-
actions:
528-
- name: team.create
529-
description: contains team create events
530-
label: Team Created
531-
- name: team.delete
532-
description: contains team delete events
533-
label: Team Deleted
534-
- name: team.member.add
535-
description: contains team member add events
536-
label: Team Member Added
537-
- name: team.member.remove
538-
description: contains team member remove events
539-
label: Team Member Removed
540-
- name: team.member.invite
541-
description: contains team member invite events
542-
label: Team Member Invited
543-
- name: member.removed
544-
description: contains org member remove events
545-
label: Organization Member Removed
546-
- name: create
547-
description: contains organization create events
548-
label: Organization Created
549-
label: Organization
550-
repo:
551-
actions:
552-
- name: create
553-
description: contains repository create events
554-
label: Repository Created
555-
- name: delete
556-
description: contains repository delete events
557-
label: Repository Deleted
558-
- name: change_privacy
559-
description: contains repository privacy change events
560-
label: Privacy Changed
561-
- name: tag.push
562-
description: contains image tag push events
563-
label: Tag Pushed
564-
- name: tag.delete
565-
description: contains image tag delete events
566-
label: Tag Deleted
567-
label: Repository
568-
'429':
569-
description: ''
570-
content:
571-
application/json:
572-
schema: {}
573-
examples:
574-
response:
575-
value:
576-
detail: Rate limit exceeded
577-
error: false
578-
'500':
579-
description: ''
580-
content:
581-
application/json:
582-
schema: {}
583-
default:
584-
description: An unexpected error response.
585-
content:
586-
application/json:
587-
schema:
588-
$ref: '#/components/schemas/rpcStatus'
589-
parameters:
590-
- name: account
591-
description: Namespace to query audit log actions for.
592-
in: path
593-
required: true
594-
schema:
595-
type: string
596-
tags:
597-
- audit-logs
598598
/v2/orgs/{name}/settings:
599599
parameters:
600600
- in: path
@@ -741,7 +741,6 @@ paths:
741741
'404':
742742
$ref: '#/components/responses/NotFound'
743743
/v2/orgs/{org_name}/members:
744-
x-audience: public
745744
parameters:
746745
- $ref: '#/components/parameters/org_name'
747746
- $ref: '#/components/parameters/search'
@@ -753,7 +752,15 @@ paths:
753752
get:
754753
summary: List org members
755754
description: |
756-
Returns a list of members for an organization
755+
Returns a list of members for an organization.
756+
757+
_The following fields are only visible to orgs with insights enabled._
758+
759+
- `last_logged_in_at`
760+
- `last_seen_at`
761+
- `last_desktop_version`
762+
763+
To make visible, please see [View Insights for organization users](https://docs.docker.com/admin/organization/insights/#view-insights-for-organization-users).
757764
758765
<span class="oat"></span>
759766
tags:
@@ -778,7 +785,6 @@ paths:
778785
'404':
779786
$ref: '#/components/responses/not_found'
780787
/v2/orgs/{org_name}/members/export:
781-
x-audience: public
782788
parameters:
783789
- $ref: '#/components/parameters/org_name'
784790
get:
@@ -2439,13 +2445,34 @@ components:
24392445
- owners
24402446
is_guest:
24412447
type: boolean
2442-
description: If the organization has verfied domains, members that have email addresses outside of those domains will be flagged as Guest member
2448+
description: If the organization has verfied domains, members that have email addresses outside of those domains will be flagged as guests.
24432449
example: false
24442450
primary_email:
24452451
type: string
2446-
description: User's email primary address
2452+
description: The user's email primary address.
24472453
example: [email protected]
24482454
deprecated: true
2455+
last_logged_in_at:
2456+
type: string
2457+
format: date-time
2458+
description: |
2459+
Last time the user logged in. To access this field, you must have insights visible for your organization. See
2460+
[Insights](https://docs.docker.com/admin/organization/insights/#view-insights-for-organization-users).
2461+
example: '2021-01-05T21:06:53.506400Z'
2462+
last_seen_at:
2463+
type: string
2464+
format: date-time
2465+
description: |
2466+
Last time the user was seen. To access this field, you must have insights visible for your organization. See
2467+
[Insights](https://docs.docker.com/admin/organization/insights/#view-insights-for-organization-users).
2468+
example: '2021-01-05T21:06:53.506400Z'
2469+
last_desktop_version:
2470+
type: string
2471+
description: |
2472+
Last desktop version the user used. To access this field, you must have insights visible for your organization. See
2473+
[Insights](https://docs.docker.com/admin/organization/insights/#view-insights-for-organization-users).
2474+
example: 4.29.0
2475+
24492476
org_member_paginated:
24502477
type: object
24512478
properties:
@@ -2500,6 +2527,7 @@ components:
25002527
example: Docker Inc
25012528
date_joined:
25022529
type: string
2530+
format: date-time
25032531
example: '2021-01-05T21:06:53.506400Z'
25042532
full_name:
25052533
type: string
@@ -2753,10 +2781,12 @@ components:
27532781
example: https://hub.docker.com/v2/scim/2.0/Users/d80f7c79-7730-49d8-9a41-7c42fb622d9c
27542782
created:
27552783
type: string
2784+
format: date-time
27562785
description: The creation date for the user as a RFC3339 formatted string.
27572786
example: '2022-05-20T00:54:18Z'
27582787
lastModified:
27592788
type: string
2789+
format: date-time
27602790
description: The date the user was last modified as a RFC3339 formatted string.
27612791
example: '2022-05-20T00:54:18Z'
27622792
parameters:

0 commit comments

Comments
 (0)