Sets

The User Sets in Supplejack API are groups of favourites that a user can publish. User Sets can return a list of sets from a user account, as well as returning a list of items for a specified set. Private API functions also exist to create, update and destroy sets, as well as add and remove individual records from a set.

Create a new set

Parameters Description
name required
description optional
privacy optional, default is public.
public - This set is public and it may appear in Supplejack search results.
private - This set is private. Only you can see this set.
hidden - This set is hidden. Only people you share this link with can see this set.
tags optional, Array

Example request:

POST: http://localhost:3000/sets.json?api_key={YOUR_API_KEY}

Parameters:

{
    "set": {
        "name": "Dogs and cats",
        "description": "Ugly dogs and cats",
        "privacy": "hidden",
        "tags": ["cats", "dogs"],
        "featured": false        
    }
}

Retrive a specific set

Parameters Description
id required, id of the set

Example request:

GET: http://localhost:3000/sets/{SETS_ID}.json?api_key={YOUR_API_KEY}

Example response:

{
    "set": {
        "id": "5088a4ab9e409dde2c000001",
        "name": "Dogs And Cats",
        "count": 0,
        "priority": 1,
        "featured": false,
        "approved": false,
        "created_at": "2012-10-25T02:32:11Z",
        "updated_at": "2014-09-04T01:59:11Z",
        "records": [
            {
                "record_id": 100,
                "position": 1
            },
            {
                "record_id": 101,
                "position": 2
            }
        ],
        "user": {
            "name": "Example User"
        }
    }
}

Update a set

Parameters Description
name required
description optional
privacy optional, default is public.
public - This set is public and it may appear in Supplejack search results.
private - This set is private. Only you can see this set.
hidden - This set is hidden. Only people you share this link with can see this set.
tags optional, Array
featured optional, default is false
You can set the featured parameter to true if you have an API key with admin role. Otherwise, passing featured parameter won't have an effect.
approved optional, default is false
A flag to determine approved public sets to be public. You should have an API key with admin role.
records optional, Array of record hashes
record_id - Integer, Id of a record
position - Integer, position of the record inside the set. You can specify different position value on each record to modify the order.

Example request:

PUT: http://localhost:3000/sets/{SETS_ID}.json?api_key={YOUR_API_KEY}

Parameters:

{
    "set": {
        "name": "Pretty Dogs and cats",
        "description": "Pretty dogs and cats",
        "privacy": "public",
        "tags": ["cats", "dogs", "pretty"],
        "featured": false,
        "approved": false,
        "records": [
            {
                "record_id": 78,
                "position": 1
            },
            {
                "record_id": 79,
                "position": 2
            },
            {
                "record_id": 80,
                "position": 3
            }
        ]        
    }
}

Delete a set

Deletes a specific set.

Example request:

DELETE: http://localhost:3000/sets/{SETS_ID}.json?api_key={YOUR_API_KEY}

List all public sets

Get information of all public sets. The API key should have an admin role.

Example request:

GET: http://localhost:3000/sets/public.json?api_key={YOUR_API_KEY}

Example response:

{
    "sets": [
        {
            "id": "5088a4ab9e409dde2c000001",
            "name": "Dogs And Cats",
            "count": 0,
            "priority": 1,
            "featured": false,
            "approved": true,
            "created_at": "2012-10-25T02:32:11Z",
            "updated_at": "2014-09-04T01:59:11Z",
            "records": [
                {
                    "record_id": 100,
                    "position": 1
                },
                {
                    "record_id": 101,
                    "position": 2
                }
            ],
            "user": {
                "name": "Administrator"
            }
        }
    ]
}

Get information of all featured sets. Featured sets are sets that are tagged as featured.

Example request:

GET: http://localhost:3000/sets/featured.json?api_key={YOUR_API_KEY}

Example response:

{
    "sets": [
        {
            "id": "5088a4ab9e409dde2c000001",
            "name": "Dogs And Cats",
            "count": 0,
            "priority": 1,
            "featured": true,
            "approved": false,
            "created_at": "2012-10-25T02:32:11Z",
            "updated_at": "2014-09-04T01:59:11Z",
            "records": [
                {
                    "record_id": 100,
                    "position": 1
                },
                {
                    "record_id": 101,
                    "position": 2
                }
            ],
            "user": {
                "name": "Administrator"
            }
        }
    ]
}

Set Items

Add an item

Adds a new record/item to a set.

Parameters Description
id required
record required, Hash
record_id - Integer, Id of a record
position - Integer, position of the record inside the set

Example request:

POST: http://localhost:3000/sets/{SETS_ID}/records.json?api_key={YOUR_API_KEY}

Parameter:

{
    "record": {
        "record_id": 90,
        "position": 1
    }
}

Update an item (position)

The only field that you can update in items inside a set is the position field. You can update the position by doing the same request in Update a set section.

Given that we have the following order of items in a set:

Record ID Position
78 1
79 2
80 3

And we want to update the position to this:

Record ID Position
80 1
79 2
78 3

Example request:

PUT: http://localhost:3000/sets/{SETS_ID}.json?api_key={YOUR_API_KEY}

Parameters:

{
    "set": {
        "name": "Pretty Dogs and cats",
        "description": "Pretty dogs and cats",
        "privacy": "public",
        "tags": ["cats", "dogs", "pretty"],
        "featured": false,
        "approved": false,
        "records": [
            {
                "record_id": 80,
                "position": 1
            },
            {
                "record_id": 79,
                "position": 2
            },
            {
                "record_id": 78,
                "position": 3
            }
        ]        
    }
}

Delete an item

Example request:

DELETE: http://localhost:3000/sets/{SETS_ID}/records/{RECORD_ID}?api_key={YOUR_API_KEY}