We can manipulate the documents existing in the VTEX Master Data using HTTP request, and it's like the most important thing we should know to dominate this platform's tool.

The official Master Data API documentation breaks down the different HTTP request we can use and explains each part of the request but this information wasn't enough for me to create a working code.

Using and old technique known as "try and failure" I came up with four working jQuery AJAX requests ready to be used to GET, POST, PATCH and PUT data in a specific Data Entity.

Differences between POST, PATCH and PUT in VTEX Master Data

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.

Nahuel SanchezNahuel Sanchez

My goal was to simplify the interaction with the VTEX Master Data during the implementation of a VTEX store. The code is far from perfect but it's a working start.

GET

function getFromMasterData(name, where, fields) {
    var store = 'storeName';
    var urlProtocol = window.location.protocol;
    var apiUrl = urlProtocol + '//api.vtex.com/' + store + '/dataentities/' + name + '/search?_where=' + where + '&_fields='+ fields;
    var response;

    $.ajax({
        "headers": {
            "Accept": "application/vnd.vtex.masterdata.v10.profileSchema+json"
        },
        "url": apiUrl,
        "async" : false,
        "crossDomain": true,
        "type": "GET"
    }).success(function(data) {
        response = data[0];
    }).fail(function(data) {
        response = data;
    });

    return response;
}

The first parameter here, name, refers to the Data Entity's acronym (for example, CL for the Client's Data Entity) and it's the same for the next HTTP requests.

The second parameter, where allows us to define the filter to use while requesting the documents from the Master Data. For example, email=johndoe@example.com.

Finally, fields is there to specify what attributes we want to retrieve from the results.

Here's an example to retrieve the first name and last name from a client knowing its email address.

getFromMasterData('CL', 'email=johndoe@example.com', 'firstName,lastName')

POST

function postInMasterData(name, email, fields) {
    var store = 'storeName';
    var urlProtocol = window.location.protocol;
    var apiUrl = urlProtocol + '//api.vtexcrm.com.br/' + store + '/dataentities/' + name + '/documents';
    var response;

    var who = {
        "email": email
    };

    var data = $.extend(who, fields);

    $.ajax({
        "headers": {
            "Accept": "application/vnd.vtex.ds.v10+json",
            "Content-Type": "application/json"
        },
        "url": apiUrl,
        "async" : false,
        "crossDomain": true,
        "type": "POST",
        "data": JSON.stringify(data)
    }).success(function(data) {
        response = data;
    }).fail(function(data) {
        response = data;
    });
    
    return response;
}

In this case, email needs to be an actual email address that the code is going to use as an unique identifier of the document that is going to be created on the Master Data, and fields is a JSON object with the attributes and values to send in the request.

Life is better with examples.

var someAttributes = {
     firstName : 'John',
     lastName : 'Doe'
};

postInMasterData('CL', 'johndoe@example.com', someAttributes);

PATCH

function patchInMasterData(name, email, fields) {
    var store = 'storeName';
    var urlProtocol = window.location.protocol;
    var apiUrl = urlProtocol + '//api.vtexcrm.com.br/' + store + '/dataentities/' + name + '/documents';
    var response;

    var who = {
        "email": email
    };

    var data = $.extend(who, fields);

    $.ajax({
        "headers": {
            "Accept": "application/vnd.vtex.masterdata.v10+json",
            "Content-Type": "application/json"
        },
        "url": apiUrl,
        "async" : false,
        "crossDomain": true,
        "type": "PATCH",
        "data": JSON.stringify(data)
    }).success(function(data) {
        response = data;
    }).fail(function(data) {
        response = data;
    });
    
    return response;
}

The parameters here works just as the POST's example, where email is the way to identify the document is going to be edited and fields the JSON object with the attributes and values, as show in the following example.

var someAttributes = {
     firstName : 'John'
};

patchInMasterData('CL', 'johndoe@example.com', someAttributes);

PUT

function putInMasterData(name, email, fields) {
    var store = 'storeName';
    var urlProtocol = window.location.protocol;
    var apiUrl = urlProtocol + '//api.vtexcrm.com.br/' + store + '/dataentities/' + name + '/documents';
    var response;

    var who = {
        "email": email
    };

    var data = $.extend(who, fields);

    $.ajax({
        "headers": {
            "Accept": "application/vnd.vtex.masterdata.v10+json",
            "Content-Type": "application/json"
        },
        "url": apiUrl,
        "async" : false,
        "crossDomain": true,
        "type": "PUT",
        "data": JSON.stringify(data)
    }).success(function(data) {
        response = data;
    }).fail(function(data) {
        response = data;
    });
    
    return response;
}

More of the same, just like the last two codes. And a similar example.

var someAttributes = {
     lastName : 'Doe'
};

putInMasterData('CL', 'johndoe@example.com', someAttributes);

This is on GitHub

I decided to put this snippets on a Git repository you can find in https://github.com/nahuelsanchez/vtexmasterdataapiconnection.

Feel free to send any improvement you think this code desperately needs (thanks in advance).

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.