Skip to content
This repository was archived by the owner on Nov 24, 2025. It is now read-only.

Make users use same representation across endpoints #6832

Merged
shamrickus merged 14 commits into from
May 23, 2022
Merged

Make users use same representation across endpoints #6832

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
cc06c1a
Convert APIv4 user/current response to use APIv4 /users representation
ocket8888 May 13, 2022
fc16cb2
Add function to convert ozzo errors to errors and join them in one step
ocket8888 May 13, 2022
040b3bb
Make user/current GET requests return UserV40s, remove ConfirmLocalPa…
ocket8888 May 13, 2022
52113df
Fix ToError never returning a nil error
ocket8888 May 13, 2022
d69b439
Fix unable to update user through APIv4
ocket8888 May 13, 2022
b42e288
Fix APIv4/Go client integration test compilation errors
ocket8888 May 13, 2022
2aea0ab
Better error handling
ocket8888 May 13, 2022
4591093
Fix Go APIv4 client using incorrect body structure for PUT /user/current
ocket8888 May 13, 2022
9dc4c6e
Fix `changeLogCount` null in POST responses
ocket8888 May 13, 2022
d071d84
Update documentation
ocket8888 May 13, 2022
8b2ea03
Update Traffic Portal to account for the new user structure
ocket8888 May 14, 2022
040dbad
Update changelog
ocket8888 May 14, 2022
e8a93e2
Fix broken footnote linking
ocket8888 May 20, 2022
b1a209c
Fix unnecessarily duplicated expression
ocket8888 May 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,12 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
- Fixed TO API `PUT /servers/:id/status` to only queue updates on the same CDN as the updated server
- t3c-generate fix for combining remapconfig and cachekeyconfig parameters for MakeRemapDotConfig call.
- [#6780](https://github.com/apache/trafficcontrol/issues/6780) Fixed t3c to use secondary parents when there are no primary parents available.
- Correction where using the placeholder __HOSTNAME__ in "unknown" files (others than the defaults ones), was being replaced by the full FQDN instead of the shot hostname.
- Correction where using the placeholder `__HOSTNAME__` in "unknown" files (others than the defaults ones), was being replaced by the full FQDN instead of the shot hostname.
- [#6800](https://github.com/apache/trafficcontrol/issues/6800) Fixed incorrect error message for `/server/details` associated with query parameters.
- [#6712](https://github.com/apache/trafficcontrol/issues/6712) - Fixed error when loading the Traffic Vault schema from `create_tables.sql` more than once.
- [#6834](https://github.com/apache/trafficcontrol/issues/6834) - In API 4.0, fixed `GET` for `/servers` to display all profiles irrespective of the index position. Also, replaced query param `profileId` with `profileName`.
- [#6834](https://github.com/apache/trafficcontrol/issues/6834) - In API 4.0, fixed `GET` for `/servers` to display all profiles irrespective of the index position. Also, replaced query param `profileId` with `profileName`.
- [#6299](https://github.com/apache/trafficcontrol/issues/6299) User representations don't match
- [#6776](https://github.com/apache/trafficcontrol/issues/6776) User properties only required sometimes

### Removed
- Remove traffic\_portal dependencies to mitigate `npm audit` issues, specifically `grunt-concurrent`, `grunt-contrib-concat`, `grunt-contrib-cssmin`, `grunt-contrib-jsmin`, `grunt-contrib-uglify`, `grunt-contrib-htmlmin`, `grunt-newer`, and `grunt-wiredep`
Expand Down
230 changes: 144 additions & 86 deletions docs/source/api/v4/user_current.rst
View file
Open in desktop

Large diffs are not rendered by default.

206 changes: 119 additions & 87 deletions docs/source/api/v4/users.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
Retrieves all requested users.

:Auth. Required: Yes
:Roles Required: None\ [1]_
:Roles Required: None\ [#tenancy]_
Comment thread
ocket8888 marked this conversation as resolved.
Outdated
:Permissions Required: USER:READ
:Response Type: Array

Expand Down Expand Up @@ -61,23 +61,29 @@ Request Structure
.. code-block:: http
:caption: Request Example

GET /api/4.0/users?username=admin HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
GET /api/4.0/users?username=mike HTTP/1.1
User-Agent: python-requests/2.25.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...


Response Structure
------------------
:addressLine1: The user's address - including street name and number
:addressLine2: An additional address field for e.g. apartment number
:changeLogCount: The number of change log entries created by the user
:city: The name of the city wherein the user resides
:company: The name of the company for which the user works
:country: The name of the country wherein the user resides
:email: The user's email address
:fullName: The user's full name, e.g. "John Quincy Adams"
:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always ``null``
:addressLine1: The user's address - including street name and number
:addressLine2: An additional address field for e.g. apartment number
:changeLogCount: The number of change log entries created by the user
:city: The name of the city wherein the user resides
:company: The name of the company for which the user works
:country: The name of the country wherein the user resides
:email: The user's email address
:fullName: The user's full name, e.g. "John Quincy Adams"
:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always ``null``

.. deprecated:: 4.0
This field is serves no known purpose, and shouldn't be used for anything so it can be removed in the future.

:id: An integral, unique identifier for this user
:lastAuthenticated: The date and time at which the user was last authenticated, in :rfc:`3339`
:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime`
Expand All @@ -91,60 +97,64 @@ Response Structure
:tenant: The name of the tenant to which this user belongs
:tenantId: The integral, unique identifier of the tenant to which this user belongs
:ucdn: The name of the :abbr:`uCDN (Upstream Content Delivery Network)` to which the user belongs
:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always ``null``
:username: The user's username

.. versionadded:: 4.0

:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always ``null``

.. deprecated:: 4.0
This field is serves no known purpose, and shouldn't be used for anything so it can be removed in the future.

:username: The user's username

.. code-block:: http
:caption: Response Example

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: YBJLN8NbOxOvECe1RGtcwCzIPDhyhLpW56nTJHQM5WI2WUDe2mAKREpaEE72nzrfBliq1GABwJlsxq2OdhcFkw==
Permissions-Policy: interest-cohort=()
Set-Cookie: mojolicious=...; Path=/; Expires=Fri, 13 May 2022 23:16:14 GMT; Max-Age=3600; HttpOnly
Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
Date: Thu, 13 Dec 2018 01:03:53 GMT
Content-Length: 454
Date: Fri, 13 May 2022 22:16:14 GMT
Content-Length: 350

{ "response": [
{
"username": "admin",
"registrationSent": null,
"addressLine1": null,
"addressLine1": "22 Mike Wazowski You've Got Your Life Back Lane",
"addressLine2": null,
"city": null,
"changeLogCount": 0,
"city": "Monstropolis",
"company": null,
"country": null,
"email": null,
"fullName": null,
"email": "mwazowski@minc.biz",
"fullName": "Mike Wazowski",
"gid": null,
"id": 2,
"newUser": false,
"id": 3,
"lastAuthenticated": null,
"lastUpdated": "2022-05-13T22:13:54.605052Z",
"newUser": true,
"phoneNumber": null,
"postalCode": null,
"publicSshKey": null,
"registrationSent": null,
"role": "admin",
"stateOrProvince": null,
"tenant": "root",
"tenantId": 1,
"ucdn": "",
"uid": null,
"lastUpdated": "2021-08-25T14:08:13.974447-06:00",
"changeLogCount": 20,
"lastAuthenticated": "2021-07-09T14:44:10.371708-06:00"
"username": "mike"
}
]}

.. [1] While no roles are required, this endpoint does respect tenancy. A user will only be able to see, create, delete or modify other users belonging to the same tenant, or its descendants.
Comment thread
ocket8888 marked this conversation as resolved.
Outdated

``POST``
========
Creates a new user.

:Auth. Required: Yes
:Roles Required: "admin" or "operations"\ [1]_
:Roles Required: "admin" or "operations"\ [#tenancy]_
:Permissions Required: USER:CREATE, USER:READ
:Response Type: Object

Expand All @@ -154,23 +164,32 @@ Request Structure
:addressLine2: An optional field which should contain an additional address field for e.g. apartment number
:city: An optional field which should contain the name of the city wherein the user resides
:company: An optional field which should contain the name of the company for which the user works
:confirmLocalPasswd: The 'confirm' field in a new user's password specification - must match ``localPasswd``
:country: An optional field which should contain the name of the country wherein the user resides
:email: The user's email address The given email is validated (circuitously) by `GitHub user asaskevich's regular expression <https://github.com/asaskevich/govalidator/blob/9a090521c4893a35ca9a228628abf8ba93f63108/patterns.go#L7>`_ . Note that it can't actually distinguish a valid, deliverable, email address but merely ensure the email is in a commonly-found format.
:fullName: The user's full name, e.g. "John Quincy Adams"
:localPasswd: The user's password
:newUser: An optional meta field with no apparent purpose - don't use this
:phoneNumber: An optional field which should contain the user's phone number
:postalCode: An optional field which should contain the user's postal code
:publicSshKey: An optional field which should contain the user's public encryption key used for the SSH protocol
:role: The name that corresponds to the highest permission role which will be permitted to the user
:stateOrProvince: An optional field which should contain the name of the state or province in which the user resides
:tenantId: The integral, unique identifier of the tenant to which the new user shall belong
:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user

.. deprecated:: 4.0
This field is serves no known purpose, and shouldn't be used for anything so it can be removed in the future.

:localPasswd: The user's password
:newUser: An optional meta field with no apparent purpose - don't use this
:phoneNumber: An optional field which should contain the user's phone number
:postalCode: An optional field which should contain the user's postal code
:publicSshKey: An optional field which should contain the user's public encryption key used for the SSH protocol
:role: The name that corresponds to the highest permission role which will be permitted to the user
:stateOrProvince: An optional field which should contain the name of the state or province in which the user resides
:tenantId: The integral, unique identifier of the tenant to which the new user shall belong
:ucdn: The name of the :abbr:`uCDN (Upstream Content Delivery Network)` to which the user belongs

.. versionadded:: 4.0

.. note:: This field is optional if and only if tenancy is not enabled in Traffic Control
:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user

:ucdn: An optional field (only used if :abbr:`CDNi (Content Delivery Network Interconnect)` is in use) containing the name of the :abbr:`uCDN (Upstream Content Delivery Network)` to which the user belongs
:username: The new user's username
.. deprecated:: 4.0
This field is serves no known purpose, and shouldn't be used for anything so it can be removed in the future.

:username: The new user's username

.. code-block:: http
:caption: Request Example
Expand Down Expand Up @@ -199,50 +218,61 @@ Request Structure

Response Structure
------------------
:addressLine1: The user's address - including street name and number
:addressLine2: An additional address field for e.g. apartment number
:city: The name of the city wherein the user resides
:company: The name of the company for which the user works
:country: The name of the country wherein the user resides
:email: The user's email address
:fullName: The user's full name, e.g. "John Quincy Adams"
:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always ``null``
:id: An integral, unique identifier for this user
:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime`
:newUser: A meta field with no apparent purpose that is usually ``null`` unless explicitly set during creation or modification of a user via some API endpoint
:phoneNumber: The user's phone number
:postalCode: The postal code of the area in which the user resides
:publicSshKey: The user's public key used for the SSH protocol
:registrationSent: If the user was created using the :ref:`to-api-users-register` endpoint, this will be the date and time at which the registration email was sent - otherwise it will be ``null``
:role: The name of the role assigned to this user
:stateOrProvince: The name of the state or province where this user resides
:tenant: The name of the tenant to which this user belongs
:tenantId: The integral, unique identifier of the tenant to which this user belongs
:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always ``null``
:username: The user's username
:addressLine1: The user's address - including street name and number
:addressLine2: An additional address field for e.g. apartment number
:changeLogCount: The number of change log entries created by the user
:city: The name of the city wherein the user resides
:company: The name of the company for which the user works
:country: The name of the country wherein the user resides
:email: The user's email address
:fullName: The user's full name, e.g. "John Quincy Adams"
:gid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always ``null``

.. deprecated:: 4.0
This field is serves no known purpose, and shouldn't be used for anything so it can be removed in the future.

:id: An integral, unique identifier for this user
:lastAuthenticated: The date and time at which the user was last authenticated, in :rfc:`3339`
:lastUpdated: The date and time at which the user was last modified, in :ref:`non-rfc-datetime`
:newUser: A meta field with no apparent purpose that is usually ``null`` unless explicitly set during creation or modification of a user via some API endpoint
:phoneNumber: The user's phone number
:postalCode: The postal code of the area in which the user resides
:publicSshKey: The user's public key used for the SSH protocol
:registrationSent: If the user was created using the :ref:`to-api-users-register` endpoint, this will be the date and time at which the registration email was sent - otherwise it will be ``null``
:role: The name of the role assigned to this user
:stateOrProvince: The name of the state or province where this user resides
:tenant: The name of the tenant to which this user belongs
:tenantId: The integral, unique identifier of the tenant to which this user belongs
:ucdn: The name of the :abbr:`uCDN (Upstream Content Delivery Network)` to which the user belongs

.. versionadded:: 4.0

:uid: A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always ``null``

.. deprecated:: 4.0
This field is serves no known purpose, and shouldn't be used for anything so it can be removed in the future.


:username: The user's username

.. code-block:: http
:caption: Response Example

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Content-Encoding: gzip
Content-Type: application/json
Location: /api/4.0/users?id=44
Date: Thu, 13 Dec 2018 02:28:27 GMT
X-Server-Name: traffic_ops_golang/
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Location: /api/4.0/users?id=3
Permissions-Policy: interest-cohort=()
Set-Cookie: mojolicious=...; Path=/; Expires=Fri, 13 May 2022 23:13:54 GMT; Max-Age=3600; HttpOnly
Vary: Accept-Encoding
Whole-Content-Sha512: vDqbaMvgeeoIds1czqvIWlyDG8WLnCCJdF14Ub05nsE+oJOakkyeZ8odf4d0Zjtqpk01hoVo14H2tjuWPdqwgw==
Content-Length: 623
X-Server-Name: traffic_ops_golang/
Date: Fri, 13 May 2022 22:13:54 GMT
Content-Length: 382

{ "alerts": [
{
"level": "success",
"text": "user was created."
"text": "user was created.",
"level": "success"
}
],
"response": {
Expand All @@ -251,14 +281,13 @@ Response Structure
"changeLogCount": null,
"city": "Monstropolis",
"company": null,
"confirmLocalPasswd": "BFFsully",
"country": null,
"email": "mwazowski@minc.biz",
"fullName": "Mike Wazowski",
"gid": null,
"id": 26,
"lastAuthenticated": "2021-07-09T14:44:10.371708-06:00",
"lastUpdated": "2021-08-25T14:43:10.466412-06:00",
"id": 3,
"lastAuthenticated": null,
"lastUpdated": "2022-05-13T22:13:54.605052Z",
"newUser": true,
"phoneNumber": null,
"postalCode": null,
Expand All @@ -268,6 +297,9 @@ Response Structure
"stateOrProvince": null,
"tenant": "root",
"tenantId": 1,
"ucdn": "",
"uid": null,
"username": "mike"
}}

.. [#tenancy] While no roles are required, this endpoint does respect tenancy. A user will only be able to see, create, delete or modify other users belonging to the same tenant, or its descendants.
Loading