If you are using 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 any of its elements, called Data Points.
What are datasets?
DataSets are used in Editable Product templates. They are used to group sets of values (DataPoints) for selection by users during the ordering process. Each DataSet belongs to a specific company and can have one or more DataPoints which users can select from a dropdown when they fill in the template fields. Each DataPoint 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 to navigate to the desired endpoint and you get a list of all objects currently present 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 may want to update one or more of the objects. This is where new functionality comes in. PrintJob API is built around RESTful approach, so to affect a change in the contents of the object you will need to switch to a ‘PUT’ verb in your HTTP request.
Let us assume that 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 of its attributes you don’t want to change prefilled with current values as any missing attributes will be set to empty.
URL part contains an URL to dataSets endpoint and an ID of an object we want to modify (data_set_8lwpXy6JRgdDLYmBaKO9 in this case)
-u is the authentication part where username is (the part before the colon) is your API key, and 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 it’s ID remained the same while values of desired attributes have changed.
If you would like to add a new DataSet then you need to use POST verb and send the data in a very same way as in 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.
In the request, we do not supply the object ID as it does not yet exist. We send our data directly to DataSet endpoint and let it do its magic. The ID of a newly created DataSet will be included in the response.
In the case of the DataSet, there are two attributes – company and name. Company is a reference to a company present in your system and takes the form of that company’s ID. Name is just a string that will describe the DataSet. Both are required, and if you omitted any of them your request would fail and return an error describing the problem. Please refer to the documentation to see all the required attributes of objects you are working with.
If you then wanted to remove one of your DataSets you could use 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 DataSet you want to remove and a DELETE verb. Use it with care as removed items can not be restored.
NOTE: Removing DataSet with associated DataPoints will remove those DataPoints as well without any additional checks or questions. Always ensure that you are deleting correct objects and don’t try to guess the IDs of objects to delete!
DataPoints
Each DataSet contains one or (usually) more DataPoints that allow users to choose values they want to appear on their products. To retrieve and manipulate DataPoints we use the same techniques as described for the DataSets above.
Just like with DataSets belonging to a Company, DataPoints belong to a specific DataSet. To create a new DataPoint for our DataSet we would follow a similar path as we did with DataSets.
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. DataSet is a required field and needs to hold an ID of an existing DataSet.
Modifying and deleting DataPonts is very similar to DataSets and if in doubt you can consult our documentation for specific examples.
