We can thrown five different HTTP requests at the VTEX Master Data: GET, POST, PATCH, PUTCH and DELETE. GET and DELETE are very simple to understand (once for get documents and the other one to delete them), but POST, PATCH and PUT seems like they all do the same thing.

There are small differences between POST, PATCH and PUT that justify the existence of all of them, and knowing this could improve our VTEX implementation and how we interact with the Master Data.

What’s VTEX Master Data?

A database-ish that works as a CRM data repository where we can find clients’ data, orders’ information, addresses and more divided into Data Entities.

Nahuel SanchezNahuel Sanchez

POST, PATCH or PUT?

The first one, POST, allows us to create a new document in a specific Data Entity. If the document already exists we won't be able to introduce the new data into the Data Entity.

For example, if we perform a POST request to create a new client with the email johndoe@example.com and name John, but the Data Entity CL already has a client with that email address a new document won't be created.

It doesn't matter if the existing document with the email johndoe@example.com has a different name for the client. Since the email needs to be unique the request will fail and the other attributes like the name will be discards.

On the other hand, PATCH works just like POST in terms that it will create a new document, but if the document already exists then the attributes from the existing document are updated with the new values that we are sending in the request.

Take into consideration that PATCH, in the scenario where the document already exists, will update only the attributes that we are sending in the request. The attributes that exists on the document but are not mentioned in the request won't be affected.

Finally, PUT works as POST too when the document doesn't exists: it creates a new one with the values we're sending in the request.

When using PUT in an scenario where the document already exists it will cause the existing document in the Data Entity to be completed overwritten. In other words, the existing document will be deleted, a new one will be created with the attributes mentioned in the request, and the ignored attributes in the request will be empty in the final created document.

Let me recap. POST to create a new document, PATCH to create a new document if it doesn't exist or to update the values of the attributes in an existing document, and finally PUT to create a new document if it doesn't exist or to overwrite an existing document.

A friendly example

Given an empty CL Data Entity, we perform a POST to create a new document with the following JSON in the request.

{
     email : "johndoe@example.com",
     firstName : "John",
     lastName : "Doo"
}

Since the document doesn't exist, it will be created.

Then, we decided to change the lastName of the document because we spot a typo on it. For this, we use PATCH and the following JSON in the request.

{
     email : "johndoe@example.com",
     lastName : "Doe"
}

After the request the document on the Data Entity will look like the following.

{
     email : "johndoe@example.com",
     firstName : "John",
     lastName : "Doe"
}

Finally, the document became obsolete and we need to overwrite it using PUT and the following JSON.

{
     email : "johndoe@example.com",
     firstName : "Jane"
}

The existing document with that email address will be deleted and a new one will be created, as follow.

{
     email : "johndoe@example.com",
     firstName : "Jane",
     lastName : ""
}

As you saw, lastName is empty.

The VTEX Master Data is what the platform offers to look under the hood. There we can find all the clients' data, orders' information, addresses and other kind of data divided into different Data Entities.

The clients's information like first name, email address, identification, phone numbers, if the client is willing to receive newsletter or not, and other information be default or custom is not invisible or totally private for the store owner. On the contrary, it's there to be read and accessed.

Is a database-ish, that works as a CRM data repository too, the deepest you'll be able to sink considering it's a SaaS platform.

Data Entity

The data is separated into different Data Entities based on the nature of the data itself.

We have Data Entities for Clients (CL), Addresses (AD), Orders (OD), Stores (SO) and a lot more but the most important one, yet, it's the one for the Clients.

Each Data Entity has specific attributes. For example, inside CL you can find, among others, the attribute document which type is Varchar 50, attribute firstName type Varchar 50, attribute isNewsletterOptIn type Boolean, and more.

Another interesting attribute type is Relationship. For example, on the Data Entity OD (for the Orders) there's an attribute known as addressId to relate a document from OD, an order, with an address from the Data Entity AD (for the Addresses).

A little lost? Think it's a MySQL database where each Data Entity is a table and the attributes are the fields. What's left it's the manipulating of the data (add new documents, delete existing documents or edit existing ones).

The attributes have properties too. An attribute can be configured to establish permissions to read it, to edit it or to use it as filter, among other minor configurations.

The power of the VTEX Master Data comes to light when we perform request to it in order to play with the data. In order to do that we generally aim our request to a specific Data Entity with a filter to retrieve the documents that matches that filter (here we use an attribute with permission to be used as filter) and from the results we ask for specific attributes to read the values (we can do that only on attributes that have permission to be read it). If the idea is to edit the documents consider that we can only alter attributes that, as you probably already guest, have permissions to be edit it.

Remember, a VTEX store by default comes with default Data Entities and default attributes. That's not the limit. Do you need an attribute to save the favorite ice cream flavour of the customer?, you can create it.

Locating the data and other information

The best part of the VTEX Master Data is how we can manipulate it (either just to read it or to edit it) using HTTP request to GET, POST, PUT, PATCH and DELETE documents from the Data Entities. But this is not part of this post scope, feel free to check other publications tagged with VTEX Master Data to go deeper on this topic.

The data is also available via web on {store}.vtexcrm.com.br where you can play with the documents, and on {store}.ds.vtexcrm.com.br where you can configure the Data Entities and attributes.

Everything I just described about the VTEX Master Data is just a glimpse of all it can offer. Check the last two URLs in the paragraph above to discover more features.