Auth0 Home Blog Docs

Get Users / Get User Logs - Response type + Swagger issue

management-api
swagger

#1

I’ve found a couple of issues regarding these two endpoints regarding the include_totals parameter.

The current behaviour is as follows:

  • /api/v2/users?include_totals=false returns an array of users, E.g:
    [
    	{
    		"user_id": "auth0|0123456789",
    		"email": "email@domain.com",
    		...
    	},
    	...
    ]
    
  • /api/v2/users?include_totals=true returns an object representing a page of users, E.g:
    {
    	"start": 0,
    	"limit": 2,
    	"length": 2,
    	"users": [
    		{
    			"user_id": "auth0|0123456789",
    			"email": "email@domain.com",
    			...
    		},
    		...
    	],
    	"total": 17
    }
    
  • /api/v2/users/{user_id}/logs?include_totals=false returns an object with user logs and a length, E.g:
    {
    	"0": {
    		"date": "1970-01-01T01:02:03.123Z",
    		"type": "s",
    		"connection": "google-oauth2",
    		...
    	},
    	"1": {
    		"date": "1970-01-02T01:02:03.123Z",
    		"type": "s",
    		"connection": "google-oauth2",
    		...
    	},
    	...,
    	"length": 2
    }
    
  • /api/v2/users/{user_id}/logs?include_totals=true returns an object representing a page of user logs, E.g:
    {
    	"length": 2,
    	"total": 6,
    	"start": 0,
    	"limit": 2,
    	"logs": [
    		{
    			"date": "1970-01-01T01:02:03.123Z",
    			"type": "s",
    			"connection": "google-oauth2",
    			...
    		},
    		{
    			"date": "1970-01-02T01:02:03.123Z",
    			"type": "s",
    			"connection": "google-oauth2",
    			...
    		},
    		...
    	]
    }
    

The first issue is that in the Users Swagger file, the responses to both of these endpoints are defined as an array of records which is only correct for /api/v2/users?include_totals=false. To properly represent this behavour, Swagger / OpenAPI v3’s oneOf keyword is required to correctly document the difference between paged and non-paged results, but the current documentation for /api/v2/users/{user_id}/logs does not match either mode.

The second issue is that the format of the result from /api/v2/users/{user_id}/logs?include_totals=false doesn’t seem to make sense. In my opinion it should be a plain array to match /api/v2/users?include_totals=false.