Originally created by Lan B Dang, last modified on Jul 25, 2017

Intro

The X-Fields parameter in our Mozart Swagger API is provided by Flask-RESTPlus.  It is used by Flask-RESTPlus to support partial object fetching.  The syntax is to provide a comma-separated list of field names.  The use of curly braces is optional, but you will want to use it if you are trying to access nested data.

A great use case for X-Fields is when you are running a query that can pull back a lot of metadata, but you are only interested in one or two fields.  For example, in the Mozart job operations API, the /job/info will provide complete information on a job, given a payload id.

It will take some experimentation to figure out what the X-fields mask should be.  If you have a tool that will break up the nesting of the full JSON results from /job/info, you will have an advantage in constructing the mask.

JSON Example

Here is an example of the normal output for a given job id:

{
  "message": "",
  "result": {
    "status": "job-completed",
    ...
  }
}

Here is the output, if you use this X-fields mask, which drills into the job_info facts in order to determine ec2_instance_type:

{result{job{job_info{facts{ec2_instance_type}}}}}

This is the much shorter result that is returned, after filtering.

{
  "result": {
    "job": {
      "job_info": {
        "facts": {
          "ec2_instance_type": "r4.8xlarge"
        }
      }
    }
  }
}