If you use Data Sets in your editable templates, you can now allow Data Sets manipulation through our API.
You can retrieve, update, create and delete any Data Set or its elements, called Data Points.
What are Data Sets?
Data Sets are used in Editable Product templates. They are used to group sets of values (Data Points) for user selection during the ordering process. Each Data Set belongs to a specific company and can have one or more data points which users can select from a dropdown when they fill in the template fields. Each data point contains up to 9 separate columns that can store strings that would appear in the final product.
Retrieving data from API is relatively easy. All you have to do is navigate to the desired endpoint and get a list of all objects currently in the system.
Request:
curl "https://api-domain.printjob.com/v2/dataSets" -u "sk_test_key":
Response:
{
"object": "list",
"count": 2,
"data": [
{
"object": "data_set",
"attributes": {
"company": "company_YEkjyNa0q6GXMlR83Bm9",
"name": "Office Addresses"
},
"id": "data_set_8lwpXy6JRgdDLYmBaKO9",
"test_environment": true
},
{...}
],
"links": []
}
Once you get your list, you can update one or more objects. This is where new functionality comes in. PrintJob API is built around the RESTful approach, so to affect a change in the object's contents, you will need to switch to a ‘PUT’ verb in your HTTP request.
Let us assume that the first object from the truncated list above is the one that interests us. We want to change its name to ‘Company Addresses’. Let us try that.
Request:
curl -X PUT -d "attributes[company]=company_YEkjyNa0q6GXMlR83Bm9&attributes[name]=Company Addresses" "https://api-domain.printjob.com/v2/dataSets/data_set_8lwpXy6JRgdDLYmBaKO9" -u "sk_test_key":
Response:
{
"object": "data_set",
"attributes": {
"company": "company_YEkjyNa0q6GXMlR83Bm9",
"name": "Company Addresses"
},
"id": "data_set_8lwpXy6JRgdDLYmBaKO9",
"test_environment": true
}
Let’s walk through the example above.
-X PUT flag sets our request verb to PUT, which tells API that we want to modify an existing record
-d “…” contains a list of all attributes of the model with the values we chose to change.
NOTE: Remember that you need to send an entire object with all its attributes you don’t want to change prefilled with current values, as any missing attributes will be empty.
URL part contains an URL to the Data Sets endpoint and an ID of an object we want to modify (data_set_8lwpXy6JRgdDLYmBaKO9 in this case)
-u is the authentication part where the username (the part before the colon) is your API key, and the password (the part after the colon) is empty.
Request returns an updated object which you can immediately use, modify again or even delete. As you can see, its ID remained the same while the desired attribute values changed.
If you would like to add a new Data Set, you need to use the POST verb and send the data in the same way as in the case of the PUT request. Check out the example below:
Request:
curl -X POST -d "attributes[company]=company_YEkjyNa0q6GXMlR83Bm9&attributes[name]=Home Addresses" "https://api-domain.printjob.com/v2/dataSets" -u "sk_test_key":
Response:
{
"object": "data_set",
"attributes": {
"company": "company_YEkjyNa0q6GXMlR83Bm9",
"name": "Company Addresses"
},
"id": "data_set_q21ZlAJGR27Dzd6Pxpnr",
"test_environment": true
}
Please notice the differences from the previous example.
We do not supply the object ID in the request as it does not yet exist. We send our data directly to the Data Set endpoint and let it do its magic. The ID of the newly created DataSet will be included in the response.
In the case of the Data Set, there are two attributes – company and name. The company refers to a company in your system and takes the form of that company’s ID. The name is just a string that will describe the Data Set. Both are required; if you omit any of them, your request will fail and return an error describing the problem. Please refer to the documentation to see all the required attributes of the objects you work with.
If you wanted to remove one of your Data Sets, you could use a DELETE verb in your request. Example follows:
Request:
curl -X DELETE "https://api-domain.printjob.com/v2/dataSets/data_set_q21ZlAJGR27Dzd6Pxpnr" -u "sk_test_key":
Response:
{
"code": 200,
"message": "Success"
}
As you can see, this one is pretty straightforward. All you need is an ID of the Data Set you want to remove and a DELETE verb. Use it with care, as removed items can not be restored.
NOTE: Removing the Data Set with associated data points will also remove those data points without any additional checks or questions. Always ensure that you are deleting the correct objects, and don’t try to guess the IDs of objects to delete!
DataPoints
Each Data Set contains one or (usually) more data points that allow users to choose values they want to appear on their products. We use the techniques described for the Data Sets above to retrieve and manipulate data points.
Like with Data Sets belonging to a Company, data points belong to a specific data set. To create a new data point for our Data Set, we would follow a similar path as we did with Data Sets.
Request:
curl -X POST -d "attributes[name]=Main Office&attributes[sort_order]=1&attributes[value_1]=10 Some Street&attributes[value_3]=Anytown&attributes[value_4]=AN12YT&attributes[data_set]=data_set_8lwpXy6JRgdDLYmBaKO9" "https://api-domain.printjob.com/v2/dataPoints" -u "sk_test_test":
Response:
{
"object": "data_point",
"attributes": {
"data_set": "data_set_8lwpXy6JRgdDLYmBaKO9",
"name": "Main Office",
"sort_order": "1",
"value_1": "10 Some Street",
"value_2": "",
"value_3": "Anytown",
"value_4": "AN12YT",
"value_5": "",
"value_6": "",
"value_7": "",
"value_8": "",
"value_9": ""
},
"id": "data_point_wJq6G5l4xR0XzovWNeL1",
"test_environment": true
}
As you can see, we sent only the attributes we wanted to hold a value. Other attributes were set to empty. The Data Set is a required field and needs to hold an ID of an existing data set.
Modifying and deleting DataPonts is very similar to Data Sets, and if in doubt, you can consult our documentation for specific examples.