On 3/13/2018 LiftIgniter released new versions of our /model and /activity endpoints. These changes will allow us to more efficiently route requests and traffic within our model servers. We strongly recommend updating to the new version as soon as possible so that your requests can leverage our more efficient performance. We will be deprecating the existing v2 versions on June 1st 2018.
The only changes required will be to include the Javascript Key and userId in the URL path, and the addition of the API key to the Headers. The JSON structures of the request bodies remains largely the same, except for the removal of the apiKey and userId parameters.
Updated Documentation:
Please refer to our Postman collection and examples:
Import Link for Postman Collection: https://www.getpostman.com/collections/af52d5927db9db17d228.
URL Path Changes:
Current:
POST https://query.petametrics.com/v2/model
POST https://query.petametrics.com/v2/activity
New v3:
POST https://query.petametrics.com/v3/:jsk/:userId/model
POST https://query.petametrics.com/v3/:jsk/:userId/activity
:jsk is the Javascript Key for your account, which can be found in your LiftIgniter account under Settings > Access Keys. This acts as an account ID, separate from the authentication granted by your API key.
:userId is the user’s unique ID in the LiftIgniter system. If you are sending data to the /activity endpoint, you have probably assigned your own unique IDs to each user. If not, this will be the userID stored in the LiftIgniter cookie.
Header Changes:
The Headers for your request must now include "x-api-key" : "Your API Key"
JSON Changes:
The "apiKey" and "userId" parameters in the JSON body are obsolete in v3, and should be removed.
FAQ:
1) What happens if I don’t have a userId (e.g. if requesting a general set of recommendations)?
A: The userId should be removed from the path if it is not available. Valid paths in this case are:
https://query.petametrics.com/v3/:jsk//model (empty path section)
OR
https://query.petametrics.com/v3/:jsk/model (collapse path section completely)
Because the userId affects traffic routing, we strongly recommend that you do NOT use a placeholder value for the userId.
2) My userIds contain slashes or are otherwise not URL-safe - how should this be handled?
A: You will need to URL encode (`encodeURIComponent` in JavaScript, `java.net.URLEncoder.encode` in Java) the userIds if they contain URL unsafe characters. If possible, we strongly recommend that userIds be restricted to using alphanumeric, underscore and hyphen characters.
3) I am using both the API and Javascript SDK (e.g. requesting recommendations via /model, but using $p(“track”) on the client side). How does this change affect the Javascript part of my integration?
If you are using a hybrid integration, please contact Support to let us know when you will be making the switch to v3 of the API. We will be able to coordinate updating your Javascript beacon to use the new v3 close to when you launch.
There is no detriment to updating to v3 in only one integration method, as it will not affect performance negatively. If you do not notify us that you have switched, we will migrate your JS beacon to use v3 on June 1st.
You do not need to make any changes to your Javascript code in order to prepare for this change.
4) What exactly will happen on June 1st 2018 when v2 is deprecated?
Customers using a hybrid integration will have their Javascript beacon migrated to use the new v3 endpoints on our side (no action is necessary to prepare your JS code for this). We will be disabling the v2 endpoints for customers that have migrated their API integrations completely.
5) We cannot migrate our code in time for June 1st - is it possible to extend the deadline for our account?
Please get in touch with our Support team ASAP - we will work with you to ensure a smooth transition.
6) Do I need to send an ID to the /user endpoint before sending activities or recommendation requests?
No - when a new userId is seen in the URL path of these endpoints, we will automatically begin generating a new behavior profile for that ID. You do not need to 'register' a userId in any way prior to sending recommendation requests to /model or events to the /activity endpoint.
7) We are only using the API to submit inventory items - is there anything I need to do?
No. Only the /model and /activity endpoints are affected by these changes. The /inventory and /user endpoints remain the same.