Last modified November 22, 2014 by Gordon Glauser

Swrve Items API Guide

The Swrve Items API is series of functions for managing items/resources in the Swrve system. Each of these functions requires a personal key in addition to an API key.
Never call the Items API from within your app. The Items API is intended for use by app administrators to query and update Swrve resources, and is not designed for high levels of traffic. If you need to query resource information in your app, use the A/B test API functions. For more information about the A/B test API functions, see Swrve A/B Test API.
This article references Swrve’s URLs for all data and content stored in both our US and EU data centers. Click the relevant tab based on your app configuration. For more information, see How Do I Configure the Swrve SDK for EU Data Storage?

View Item

This API call gets an item (or all items) from the app (HTTP GET). This function is intended for use from your application’s resource editor. Do not call it from the app client or the app server. The A/B Test API contains an API called /resources/ that should be called from the app client or the app server. The A/B test server is designed for high-performance, high-availability serving of app resources.

Request Method

GET

URL

US

https://dashboard.swrve.com/api/1/items

EU

https://eu-dashboard.swrve.com/api/1/items

Examples

List all items in the app:

US

EU

List attributes for the item with unique ID rf65 in the app:

US

EU

URL Parameters

Parameter Presence Description
api_key Required The API key for the app.
personal_key Required The personal key for your user login.
item Optional If item is not supplied, the array of all items is returned, otherwise the item with this unique ID is returned.

Error Codes

If an error occurs while processing the request, you may receive one or more of the following error codes and need to make sure your integration is equipped to handle error conditions.

Code Text Description
400 Invalid JSON The JSON object is invalid.
403 Forbidden Invalid authorization parameters. Check that your API key is correct.
404 No matching resource found The item ID does not exist. Check the item list and verify the item ID is correct.
503 Service Unavailable An error occurred on the Swrve server side. Attempt to send the request at a later time, if possible.

Create (or Update) Item

This API call creates or updates a single item (HTTP POST).

Request Method

POST

URL

US

https://dashboard.swrve.com/api/1/items

EU

https://eu-dashboard.swrve.com/api/1/items

Examples

Create a new item in the app including a thumbnail:

US

EU

Update an existing item in the app (assuming an item teapot already exists):

US

EU

URL Parameters

Parameter Presence Description
api_key Required The API key for the app.
personal_key Required The personal key for your user login.
item Required The unique ID (UID) of an item when creating, updating or listing a single item.
data Required
This is a JSON string of key/value pairs (restricted to string and integer keys and values) that become the attributes of an item. Wrap all strings in double quotes (“), including key names.
Do not specify the UID of an item here as you have already specified it in the item parameter. Any value for UID is ignored.If no name attribute is specified in the data, the UID value is used as the item’s name.
A nil value for an attribute indicates the attribute should be removed. The created_at and updated_at fields are special parameters which set the corresponding special attributes shown on an item’s page.
To set the item’s class, include item_class; for example, data={“name”:”Teapot”, “item_class”:”Kitchenware”}.

Error Codes

See View Item.


Bulk Item Upload

This API call creates or updates a batch of items in a single HTTP POST request.

By adhering to the expected maximums (that is, the level of usage to which the Swrve service has been tuned for reasonable performance in the GUI for bulk export), you can usually avoid encountering issues with the Bulk Item API. The limit for the Bulk Item API varies (depending on the number of items modified and the size of POST data) and presents itself as a network timeout. The recommended best practice is to catch this in your code, as the Bulk Item API updates items in a transaction and will rollback if it’s unsuccessful.

Request Method

POST

URL

US

https://dashboard.swrve.com/api/1/items_bulk

EU

https://eu-dashboard.swrve.com/api/1/items_bulk

Example

Create or update two items at once:

US

EU

URL Parameters

Parameter Presence Description
api_key Required The API key for the app.
personal_key Required The personal key for your user login.
data Required
This is a JSON string where each key should be an item’s UID and each value will itself be a JSON string of key/value pairs (restricted to string and integer keys and values) that become the attributes of that item.
Wrap all strings in double quotes (“), including key names.
A nil value for an attribute indicates the attribute should be removed. The created_at and updated_at fields are special parameters which set the corresponding special attributes shown on an item’s page.
To set the item’s class, include item_class; for example, data={“item-uid”: {“name”:”Teapot”, “item_class”:”Kitchenware”}}.

Error Codes

See View Item.