Get Web App Item List

Gets a list of Web App items, as per the specified filters.

Request

  • Method: GET
  • Server: https://[app key here]-[site_ID here]-apps.worldsecuresystems.com. Take a look at the Authorize your API calls document for more info on how this URL is formed.
    • Note: When building apps always use relative request URLs. Do not use the "full" URL above because you might have problems running your app on a different site as the site_ID parameter will be different.
  • Path: /api/v2/admin/sites/[siteID]/webapps/[webAppName]/items
    • Alternatively use "current" in place of siteId for current login token's site
  • Authorization header: This should contain the authorization token. Here is how to obtain the token.
  • Required Permissions: View Web App

Filters

A query string (eg. ?order=ascending) with the following properties:

  • order - allows sorting bit a single system field, either "ascending" or "descending" (string, optional) (see the Ordering Syntax section)
  • where - filter by a single system field (string, optional) (see the Filtering syntax section)
  • skip - how many items to skip from the returned result. (integer, optional)
  • limit - how many items to return (integer, optional)

Response

A WebAppItemList object with the following properties:

  • links - contains a collection of links (array)
    • self - the API URL that returned this result
    • previous - the API URL that will return the previous page of results, if any
    • next - the API URL that will return the next page of results, if any
  • items - an array of WebAppItemSummary objects with the following properties (array)
    • links - contains a collection of links (array)
      • self - the API URL that will return the full details of this Web App item (string)
    • id - the ID of the Web App item (integer)
    • name - the name of the Web App item (string)
    • releaseDate - the release date of the Web App item, in the format yyyy-mm-dd (string)
    • expiryDate - the date the Web App will expire, in the format yyyy-mm-dd (string)
    • createDate - the date the Web App was created, in the format yyyy-mm-dd (string)
    • lastUpdateDate - the date the Web App item was last updated, in the format yyyy-mm-dd (string)
    • enabled - whether the Web App item is enabled or disabled (boolean)
  • totalitems - the number of Web App items that match the specified filter (integer)
  • skip - the number of Web App items skipped in this response (integer)
  • limit - the number of Web App items returned in this response (integer)

Accepts and returns JSON as Content-Type.


Request:

GET /api/v2/admin/sites/current/webapps/TestWebapp1/items?skip=2&limit=2 HTTPS/1.1
Authorization: 3e8d891d91eb433e9c800cebe3b132a4e64ac661c5ed4dd8bdecae0487e4ad7c
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: {length}

{
  "links": [
    {
      "rel": "self",
      "uri": "/admin/sites/current/webapps/TestWebapp1/items?skip=2&limit=2"
    },
    {
      "rel": "previous",
      "uri": "/admin/sites/current/webapps/TestWebapp1/items?skip=0&limit=2"
    },
    {
      "rel": "next",
      "uri": "/admin/sites/current/webapps/TestWebapp1/items?skip=4&limit=2"
    }
  ],
  "items": [
    {
      "links": [
        {
          "rel": "self",
          "uri": "/admin/sites/current/webapps/TestWebapp1/items/1073041"
        }
      ],
      "id": 1073041,
      "name": "item3",
      "weight": null,
      "releaseDate": "2013-06-30",
      "expiryDate": "9999-01-01",
      "createDate": "2013-06-30",
      "lastUpdateDate": "2013-06-30",
      "enabled": true
    },
    {
      "links": [
        {
          "rel": "self",
          "uri": "/admin/sites/current/webapps/TestWebapp1/items/1073042"
        }
      ],
      "id": 1073042,
      "name": "item4",
      "weight": null,
      "releaseDate": "2013-06-30",
      "expiryDate": "9999-01-01",
      "createDate": "2013-06-30",
      "lastUpdateDate": "2013-06-30",
      "enabled": true
    },
  ],
  "totalItemsCount": 7,
  "skip": 2,
  "limit": 2
}

Sample code

Sorting ascending by name

var request = $.ajax({
    url: "/api/v2/admin/sites/current/webapps/apicreated/items?order=name",
    type: "GET",
    connection: "keep-alive",
    contentType: "application/json",headers: {
        "Authorization": $.cookie('access_token')
    }
});
request.done(function (msg) {
    console.log(JSON.stringify(msg));
})
request.fail(function (jqXHR) {
    console.log("Request failed.");
    console.log("Error code: " + jqXHR.status);
    console.log("Error text: " + jqXHR.statusText);
    console.log("Response text: " + jqXHR.responseText);
}) 

Sorting descending by name

var request = $.ajax({
    url: "/api/v2/admin/sites/current/webapps/apicreated/items?order=-name",
    type: "GET",
    connection: "keep-alive",
    contentType: "application/json",headers: {
        "Authorization": $.cookie('access_token')
    }
});
request.done(function (msg) {
    console.log(JSON.stringify(msg));
})
request.fail(function (jqXHR) {
    console.log("Request failed.");
    console.log("Error code: " + jqXHR.status);
    console.log("Error text: " + jqXHR.statusText);
    console.log("Response text: " + jqXHR.responseText);
}) 

Below is some sample code using the bcapi.js SDK.

Load items paginated

var items = new BCAPI.Models.WebApp.ItemCollection("Test webapp");
items.fetch({
        skip: 10, limit: 100,
        success: function(webAppItems) {
            // handle success
        },
        error: function(webAppItems, xhr) {
            // handle errors
        }
});

items.each(function(webAppItem) {
        // display logic
});

Filtering items

var items = new BCAPI.Models.WebApp.ItemCollection("Test webapp");
items.fetch({     
        where: {"name": "Web app item new"},
        success: function(webAppItems) {
            // handle success
        },
        error: function(webAppItems, xhr) {
            // handle errors
        }
});

Ordering items

var items = new BCAPI.Models.WebApp.ItemCollection("Test webapp");
items.fetch({
        order: "-name",
        success: function(webAppItems) {
            // handle success
        },
        error: function(webAppItems, xhr) {
            // handle errors
        }
});

Filtering Syntax

Filtering is supported by constraining at most one item field. Only the specified system fields and the item's category set can be used for filtering.

The list of supported system fields is:

  • Id
  • Name
  • Weight
  • ReleaseDate
  • ExpiryDate
  • CreateDate
  • LastUpdateDate
  • Enabled

The filtering syntax involves specifying a list of constraints, logically chained using the AND operator which must apply to the one field specified. The constraints are built using the following operators:

Operator Name Example Applicable type
N/A equals (==) where={"name" : "item-name"} all
$ne not equal (!=) where={"id": {"$ne": 42}} all
$lt less than (<) where={"weight" : {"$lt": 3}} all
$lte less than or equal (<=) where={"name" : {"$lte": "omega"}} all
$gt greater than (>) where={"releaseDate" : {"$gt": "jun 10 2012"}} all
$gte greater than or equal (>=) where={"name" : {"$gte": "alpha"}} all
$contains contains where={"name": {"$contains": "delta"}} string-only
$beginsWith begins with where={"name": {"$beginsWith": "prefix"}} string-only

Important Notes

  • Multiple constraints can be chained, and the chaining operator is AND. We do not support OR-queries

    where={"name": {"$gt": "alpha", "$lt": "omega", "$contains":"foo"}}

  • Equality has no dedicated operator and it cannot be chained together with other constraints. The only way to specify that something must equal a value is like so:

    where={"name": "epsilon"}

  • To check that an item is labeled with a certain category the following syntax must be used:

    where={"category": "/my/category/path"}

  • The category is specified as a category-path string or by providing the category's numeric id. The path should start with a /. If it does not, the / will be added automatically to the category string. The following is equivalent to the previous example:

    where={"category": "my/category/path"}

  • Field names, and the category label are case-insensitive
  • null-values will returns false for every comparison except equality and $ne operator. These two operators can be used to filter out the items that have missing values for certain fields

    where={"weight": null} where={"weight": {"$ne": null}}

Examples

  • Filtering by name

    GET /api/v2/admin/sites/current/webapps/TestWebapp1/items?where={"name": {"$contains": "item"}}

  • Filtering by date

    GET /api/v2/admin/sites/current/webapps/TestWebapp1/items?where={"createDate": {"$gte": "2001-01-01", "$lte": "2013-01-01"}}

  • Filtering by category id

    GET /api/v2/admin/sites/current/webapps/TestWebapp1/items?where={"category": 123}

  • Filtering by category path

    GET /api/v2/admin/sites/current/webapps/TestWebapp1/items?where={"category": "my-label"}

Ordering Syntax

The order query parameter specifies which field will be used to order the results of the query. Only the following system fields can be used to order the results:

  • Id
  • Name
  • Weight
  • ReleaseDate
  • ExpiryDate
  • CreateDate
  • LastUpdateDate
  • Enabled

To order the results in ascending order, just provide the system field name. If the results are to be sorted in descending order prefix the system field name with a - (dash).

If no ordering is specified the items will be order by name ascending.

When sorting the items using a specified field, in case of ties due to equal values for that field, items will be further sorted by name.


Error codes

This method will return the following error codes:

  • 200 - success
  • 400 - bad request
    • 190001 - the Web App could not be found (the webAppName parameter from the URL does not match any record)
    • 200000 - an unspecified error has occurred
    • 200007 - there is a problem with the query, eg. invalid format, invalid field name, invalid operator, etc.
    • 200009 - the category path specified in the query doesn't exist
  • 401 - unauthorized - when the Authorization header is not present, or contains an invalid site token
    • 101000 - sub-error code
  • 403 - forbidden - this is returned when the user trying to access the API does not have the proper permissions