Prerequisites
In order to have access to User API, you must have permits on the following authorization layers:
- You will have app credentials (client ID and client secret). You can create app credentials for your site via DRUID cockpit.
- The app credentials must be active.
- The app credentials must be authorized to obtain application tokens via client_credentials mechanism (see permissions tab in apps configuration).
- The app must be authorized to access User API resource server (see perrmissions tab in apps configuration)
Description
The User API is used so that applications integrated with DRUID can consult the personal data of the users registered in your database. The API posts operations that use the access tokens and client tokens obtained in the OAuth authentication process.
Endpoint URL
POST https://{your-endpoint-domain.com}/api/user
Request headers
| Field | Value |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
Request parameters
| Field | Description | Required | Type |
|---|---|---|---|
| oauth_token | client token obtained in the OAuth process. It can also be an access token, in which case the data relating to the user that generated the token will be returned. | yes | string |
| f | f: would be the equivalent of “from” in a query. For the time being, it should take the User value | no | string |
| s | would be the equivalent of “select” in a query. With s=* you’ll get all the user fields. With s=? where ? is the name of a field (see field names). You’ll only get that user field and as many field names as you want can be nested by adding more than one s=?. | no | string |
| w | The equivalent of the “where” clause in a query. With w.?=value where ? is the name of a field (see field names) you’ll only get data of users that meet the condition. where conditions may be nested in the form w.field1=value1& w.field2=value2&w.field3=value3 … | no | string |
Response json example
Response parameters
| Type | Field | Description | Whereable | Selectable |
|---|---|---|---|---|
| Unique | id | Unique identifier for the user | yes | yes |
| Unique | oid | The unique identifier given the user entity. | no | no |
| Unique | screen_name | |||
| Unique | national_id | |||
| flag | opt-in | Determines whether the user accepts to receive communications | yes | no |
| enum | property | The name of the property associated with the entry point by which the user is registered | yes | no |
| string | entry-point | The entry-point key by which the user is registered | yes | no |
| string | country_iso_code | Usually determines the origin country of the user. Exactly is the country code associated with the entry-point for which the user registered. see https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes | no | no |
| enum | typologies | List of typologies to which the user belongs | no | no |
| flag | confirmed | It determines whether the user has confirmed at least one identifier (see identifiers table). | no | no |
| enum | brand | The corresponding brand of the registered user. Exactly is the associated brand with the entry-point for which the user registered. | no | no |
| Unique | facebook_id | |||
| Unique | twitter_id | |||
| Unique | linkedin_id | |||
| Unique | google_plus_id | |||
| Unique | windows_live_id | |||
| Unique | instagram_id | |||
| birthday | ||||
| sex | ||||
| address | ||||
| town | ||||
| name | ||||
| surname | ||||
| phone_number |
Examples
Tips and cautions on using user data query
About the parity table
It’s probable that the consumer application of the user API service needs to maintain a parity table between your own application and DRUID users. This table would relate the identifier of the application user with the identifier returned by the DRUID User API.
The consumer application may not even have own users but works directly with DRUID users and it wants to save this user identifier.
For either of the cases, we recommen saving this information (relation if it doesn’t exist or new user if it doesn’t exist) when the user first authenticates and their data subsequently consulted through this API.
About storing user data retrieved from User API
It is not recommended (except in exceptional cases) that the data of a user consulted using the User API, such as name, mail, etc., are stored by the consumer application of the service. This primarily for two reasons:
- Possible referential integrity errors between the User API data and the application consuming the API. As if the user updates their data, the data will be different between the two systems.
- Possible legal issues regarding data management. If the consumer application wants to store the data returned by the API, it must undergo the neccesary processes to maintain data confidentiality and legality with your Company.