Facets API

Owned by Patrice Neff
Last updated: Sept 08, 2016
3 min read

Manage facets on a project. Facets control the item keywords, specifically their data types and whether or not they are visible to users.

Methods

Get Facets

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/facets

Returns the known facets on a project. Every keyword that has ever been seen in the project's index will be included here.

Note: facets are never removed from an index.


Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
Headers:See Common Headers.
Status Codes:
  • 200 – Results returned.

See also Common Status Codes.

Returns:

Response fields:

  • facets – List of facets.


{
    "facets": [
        {
            "display_name": "Issue Reporter",
            "name": "reporter",
            "data_type": "string",
            "group_name": "By field",
            "visible": true,
            "id": "fba89f9e644caeebe1a444d0cbf33364d50d9b49f91ce7bebf167cc1834ea550"
        },
        {
            "display_name": "Comment Count",
            "name": "comment_count",
            "data_type": "int",
            "group_name": "By field",
            "visible": true,
            "id": "a665d30abd88e397251bce536664bcdbfb8163c874459eebc813b42d7fc36def"
        }
    ]
}


Create Facet

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/facets

Changes the settings for a single facet.

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
JSON Data:

Data is passed in as a JSON object.

Valid object keys:

  • name – The name of the facet. This is the name with which the facet is referenced in an item's keyword list.
  • display_name – The name with which that facet is displayed to the user.
  • data_type – The facet's data type. See the section Data Types below for the available data types.
  • visible – Boolean indicating whether the facet is visible to the user.
  • group_name – The group under which this facet is displayed.

Only the name key is required. All other keys are optional.

Example request body:

{
    "display_name": "Comment Count",
    "name": "comment_count",
    "data_type": "int",
    "group_name": "Metadata",
    "visible": true
}
Headers:See Common Headers.
Status Codes:
  • 201 – Facet created.
  • 409 – A facet with the same name already exists.

See also Common Status Codes.

Returns:

The created facet.

{
    "display_name": "Comment Count",
    "name": "comment_count",
    "data_type": "int",
    "group_name": "Metadata",
    "visible": true,
    "id": "a665d30abd88e397251bce536664bcdbfb8163c874459eebc813b42d7fc36def"
}

Get Facet

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/facets/(id: facet_id)

Returns a single facet from the project.

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
  • facet_id – Facet identifier.
Headers:See Common Headers.
Status Codes:
  • 200 – Facet returned.

See also Common Status Codes.

Returns:

The facet.

{
    "display_name": "comment_count",
    "name": "comment_count",
    "data_type": "int",
    "group_name": "By field",
    "visible": true,
    "id": "a665d30abd88e397251bce536664bcdbfb8163c874459eebc813b42d7fc36def"
}

Update Facet

PUT https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/facets/(id: facet_id)

Changes the settings for a single facet.

Parameters:
  • tenant – User tenant.
  • project_id – Project identifier.
  • facet_id – Facet identifier.
JSON Data:

Data is passed in as a JSON object.

Valid object keys:

  • display_name – The name with which that facet is displayed to the user.
  • visible – Boolean indicating whether the facet is visible to the user.
  • group_name – The group under which this facet is displayed.

All keys are optional and keys that are not passed in are not modified.

Example request body:

{
    "display_name": "Comment Count"
}
Headers:See Common Headers.
Status Codes:
  • 200 – Modified facet returned.

See also Common Status Codes.

Returns:

The updated facet.

{
    "display_name": "Comment Count",
    "name": "comment_count",
    "data_type": "int",
    "group_name": "By field",
    "visible": true,
    "id": "a665d30abd88e397251bce536664bcdbfb8163c874459eebc813b42d7fc36def"
}


Data Types

Facets have an associated data type. That data type is validated when data flows into the system.

The following table documents the available data types and example JSON values for each type.

Data typeDetailsExample
stringThis is the default type. Used for any sequence of characters (Unicode allowed)."Any string here"
intNumeric data type for integers.12
floatNumeric data type for floating point numbers.189.421
datetimeDate/time values. Follows Squirro's standard date and time format and should be in the UTC time zone for best results."2015-06-06T06:28:12"