/filters/{id}

GET

Get document describing the filter

Responses

200: The filter was found and document is returned

Example value
{
  "description": "A model for the response body when creating a new filter",
  "allOf": [
    {
      "description": "A description of a job to generate a customised dataset\n",
      "type": "object",
      "properties": {
        "filter_id": {
          "description": "A unique id for this resource",
          "type": "string",
          "readOnly": true
        },
        "links": {
          "description": "A list of links related to this resource",
          "type": "object",
          "properties": {
            "dimensions": {
              "type": "object",
              "properties": {
                "href": {
                  "description": "A URL to list the dimensions selected for the filter",
                  "type": "string",
                  "example": "http://localhost:8080/filters/51f5f643-0633-45be-ae82-63ff4149f665/dimensions"
                }
              }
            },
            "self": {
              "type": "object",
              "properties": {
                "href": {
                  "description": "A URL to link to the filter record",
                  "type": "string",
                  "example": "http://localhost:8080/filters/51f5f643-0633-45be-ae82-63ff4149f665"
                }
              }
            },
            "version": {
              "type": "object",
              "properties": {
                "href": {
                  "description": "A URL to the version being filtered",
                  "type": "string",
                  "example": "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/editions/2017/version/1"
                },
                "id": {
                  "description": "An ID of the version being filtered",
                  "type": "string",
                  "example": "de3bc0b6-d6c4-4e20-917e-95d7ea8c91dc"
                }
              }
            }
          },
          "readOnly": true
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "dataset": {
          "description": "A version of an edition for a dataset to filter on.",
          "type": "object",
          "properties": {
            "edition": {
              "description": "An edition of a dataset",
              "type": "string"
            },
            "id": {
              "description": "The unique identifier of a dataset",
              "type": "string"
            },
            "version": {
              "description": "A version of a dataset",
              "type": "integer"
            }
          }
        },
        "instance_id": {
          "description": "The instance of a dataset this filter relates to",
          "type": "string",
          "readOnly": true
        },
        "population_type": {
          "description": "The population type that the filter is based on, this is for Census filters only",
          "type": "string",
          "readOnly": true
        },
        "published": {
          "description": "Whether the dataset the filter relates to is published or not",
          "type": "boolean",
          "readOnly": true
        },
        "type": {
          "description": "The type of filter, e.g. flexible for census filters",
          "type": "string",
          "readOnly": true
        }
      }
    }
  ]
}

404: Filter not found

Example value
null

500: Failed to process the request due to an internal error

Example value
null

PUT

Update the filter by providing new properties, submit a filter for processing by setting query parameter `submitted` to `true`. This endpoint is for CMD datasets only.

Parameters

Name Type Description
submitted query A flag to indicate the submission of a filter
filter body Model of all editable properties within a filter
If-Match header Filter resource version, as returned by a previous ETag, to be validated; or '*' to skip the version check
id path The unique filter ID for customising a dataset

Responses

200: The filter job has been updated

Example value
{
  "description": "A model for the response body when updating a filter",
  "allOf": [
    {
      "description": "A description of a job to generate a customised dataset\n",
      "type": "object",
      "properties": {
        "filter_id": {
          "description": "A unique id for this resource",
          "type": "string",
          "readOnly": true
        },
        "links": {
          "description": "A list of links related to this resource",
          "type": "object",
          "properties": {
            "dimensions": {
              "type": "object",
              "properties": {
                "href": {
                  "description": "A URL to list the dimensions selected for the filter",
                  "type": "string",
                  "example": "http://localhost:8080/filters/51f5f643-0633-45be-ae82-63ff4149f665/dimensions"
                }
              }
            },
            "self": {
              "type": "object",
              "properties": {
                "href": {
                  "description": "A URL to link to the filter record",
                  "type": "string",
                  "example": "http://localhost:8080/filters/51f5f643-0633-45be-ae82-63ff4149f665"
                }
              }
            },
            "version": {
              "type": "object",
              "properties": {
                "href": {
                  "description": "A URL to the version being filtered",
                  "type": "string",
                  "example": "http://localhost:8080/datasets/DE3BC0B6-D6C4-4E20-917E-95D7EA8C91DC/editions/2017/version/1"
                },
                "id": {
                  "description": "An ID of the version being filtered",
                  "type": "string",
                  "example": "de3bc0b6-d6c4-4e20-917e-95d7ea8c91dc"
                }
              }
            }
          },
          "readOnly": true
        }
      }
    },
    {
      "type": "object",
      "properties": {
        "dataset": {
          "description": "A version of an edition for a dataset to filter on.",
          "type": "object",
          "properties": {
            "edition": {
              "description": "An edition of a dataset",
              "type": "string"
            },
            "id": {
              "description": "The unique identifier of a dataset",
              "type": "string"
            },
            "version": {
              "description": "A version of a dataset",
              "type": "integer"
            }
          }
        },
        "dimensions": {
          "description": "A list of dimensions in the filter job",
          "type": "array",
          "items": {
            "description": "A dimension to filter on a dataset. Information on a dimension can be gathered using the `Dataset API`",
            "type": "object",
            "properties": {
              "name": {
                "description": "The name of the dimension to filter on",
                "type": "string"
              },
              "options": {
                "description": "A list of options for dimension to filter on a dataset",
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        },
        "instance_id": {
          "description": "A unique id for this resource",
          "type": "string",
          "readOnly": true
        },
        "links": {
          "type": "object",
          "properties": {
            "filter_output": {
              "description": "A link object containing the url to the filter output document, this is only returned once the submitted query parameter is set to true.",
              "type": "object",
              "properties": {
                "href": {
                  "description": "A URL to the filter output document",
                  "type": "string",
                  "example": "http://localhost:8080/filter-outputs/95c4669b-3ae9-4ba7-b690-87e890a1c543"
                },
                "id": {
                  "description": "An ID of the created filter output document",
                  "type": "string",
                  "example": "95c4669b-3ae9-4ba7-b690-87e890a1c543"
                }
              }
            }
          }
        },
        "published": {
          "description": "Indicates if the dataset is published or not",
          "type": "boolean",
          "readOnly": true
        }
      }
    }
  ]
}

400: Invalid request body or If-Match header not provided

Example value
null

404: Filter not found

Example value
null

409: #/responses/FilterConflict

Example value
null

422: Unprocessable entity - instance has been removed

Example value
null

500: Failed to process the request due to an internal error

Example value
null