The SafeData app provides an easy to use, configurable middleware to retrieve and save MasterData (V1 & V2) information directly on the front-end (or through another back-end as well).
It works by acting as an validation/authorization layer on top of masterdata api to ensure the data being queried/changed belongs to the user executing the action.
You can install it through the app store or the command-line interface:
vtex install vtex.safedata@0.x
The base configurations for CL (Client) and AD (Address) entities are automatically configured but can be changed by using the app settings interface (this is currently a work-in-progress)
Upon installing, some public routes will become instantly available to use.
SafeData respects the same MasterData routes which can be accessed by replacing api/dataentities
for safedata
:
Let's say we need to query the address AD
entity by the addressName (addressName=12345
):
#####For IO Stores: You can use it directly like this:
GET https://myaccount.myvtex.com/safedata/AD/search?_where=addressName=12345
#####For Non-IO Stores:
If you're implementing SafeData in a store which doesn't use Store Framework, you need to insert the path api/io
to your endpoint before safedata
, like this:
GET https://myaccount.myvtex.com/api/io/safedata/AD/search?_where=addressName=12345
As of this writing, SafeData supports the following routes:
Get document:
GET /safedata/{entity}/documents/{documentId}
Search documents:
GET /safedata/{entity}/search
Create document:
POST /safedata/{entity}/documents
Create or update document:
PATCH /safedata/{entity}/documents
Entire document update:
PUT /safedata/{entity}/documents/{documentId}
Partial document update:
PATCH /safedata/{entity}/documents/{documentId}
All underscore query parameters are supported (_where, _fields, _schema and so on)
When a client is making their first purchase, the CL
entity may be created preemptively if the store has specific customizations to include new fields in the checkout process (e.g. birth date). This could cause problems since SafeData forbids customers to change personal data when they're not logged in. To avoid this problem, you can add the query parameter _orderFormId
so SafeData can ensure the customer can safely change their information since it's their first checkout.
Example:
PATCH /safedata/CL/documents?_orderFormId=7217c9c7413142dd93e3b715f95cd03d
with this payload:
{
"email": "my_email@domain.com",
"birthDate": "1990-10-11T00:00:00"
}
When this request is called for the first time the user does not exist, so it's allowed to be created anonymously.
In subsequent calls, SafeData checks the _orderFormId
to ensure the user was created in this checkout session, so they can update their information without asking for credentials.
This allows users to update their personal information during the checkout process without logging in, ONLY during the first purchase.
Once a purchase is finished, a complete profile is generated, and in order to update this information again the user has to log in (as expected by design)
Please be aware that currently ONLY the PATCH /documents
route supports the _orderFormId
parameter, and that it only works with entities that contain an email
field in their schema.
The whole process is based on the CL
entity, which is used as a guide to identify the user. First, we reach out to Vtex ID to confirm the StoreUserAuthToken
is valid and get the user e-mail. Then we retrieve only the necessary fields on the CL
entity to ensure the user is manipulating/obtaining only entities that belongs to them.
This is done through a field comparison between CL
and whatever entity is being queried. For instance, when searching for documents of the AD
entity, we compare their userId
to the id
found in the CL
entity, and the action is only allowed if they match.
Please be aware that the comparison fields MUST be searchable/filterable. (They don't have to be public though, and in fact making any fields public is disencouraged)
It is possible to allow other MasterData entities to follow these rules by registering them on the app settings:
Please be aware that the field options are currently unavailable, and users are allowed to update any fields.
Querying and updating information through SafeData is by definition slower than doing so directly on MasterData, because of all the extra security checks. However, preliminary tests have shown that:
- The median execution time for create/update operations stays below 200ms
- Search operations depend heavily on the queries, but the median execution time stays between 50-100ms
- Get operations are very fast and usually take around 25ms
- Obtaining the current user credentials takes around 15ms per request
- Delete operation
- White-listing updateable fields
- Scroll operation