Anatomy of a YAML file

This article lists all supported objects you can use inside your Data app YAML file and provides best practices guidance on using them. The object hierarchy is represented using dot notation. In other words, if you're looking at schema.types.title, this means that the schema object must be at the root level of your YAML file, it contains a collection of types and each type has a title property.

Sample Data App YAML file

In its most simple form, a complete Data app YAML file looks something like this:

kind: rest
baseUrl: "{url-to-the-3rd-party-rest-api}"
dateFormat: "yyyy-MM-dd'T'HH:mm:ss"
connectionTest:
    uri: ""    
    verb: GET
    headers:
        accept: "application/json"

schema:
    types:
        -
            title: ""
            key: ""
            staticFields:
                -
                    name: ""
                    title: ""
                    type: ""
            download:
                uri: "{uri-path}"
                verb: GET
                headers:
                    accept: "application/json"
                response:
                    collection: ""

You can use this template to start creating your first Data apps. You can also use the App Boilerplates tool to generate sample Data app templates.

YAML file properties

kind

kind: rest

Currently the only supported kind for a Data app is rest. This kind indicates the app is pulling data from a REST API.

baseUrl

baseUrl: "https://api.weather.gov"

This is the base url of your REST API. It will be used in combination with the endpoint uri paths specified in the download section of each type when downloading its data.

dateFormat

dateFormat: "yyyy-MM-dd'T'HH:mm:ss"

This setting allows you to specify the format of the date fields. The format should match the format coming from the API response. Examples:

  • dateFormat: "yyyy-MM-dd'T'HH:mm:ss"
  • dateFormat: "yyyy-MM-dd'T'HH:mm:ss'Z'"
  • dateFormat: "yyyy-MM-dd'T'HH:mm:ss.mmm'Z'"

connectionTest

    connectionTest:
      uri: "/planets"
      verb: "GET"
      headers:
          Accept: "application/json"

Your Data app uses this object to perform a REST call on the specified uri during the connection set up steps. The app uses the response from this API call to determine successful connectivity (Response code between 200-399). While this is not a mandatory property it’s recommended to have one as this makes the identification of potential problems easier.

connectionTest.uri

uri: "https://api.weather.gov"

The URL on which the rest call will be made. A response code between 200 and 399 is expected.

connectionTest.verb

verb: GET

The HTTP method (verb) to use. Supported methods are GET and POST.

connectionTest.headers

  headers:
    accept: "application/json"
    content-type: "application/json"

Any HTTP headers needed for the connection test request. If you must pass more that one header, list each ona new line

schema

This is the start of the data type definition, where we define what tables and columns we’re going to pull from the API

schema.types

This is the list of entities being pulled from the API. Defining at least one type is required.

schema.types.title

    title: "Glossary"

The title for the type. This is what the user will see available for selection in the Add datasource screen.

schema.types.key

    key: "nws_glossary"

This is the unique key that will serve as table name for the entity. It's used not only for persistence, but also in the insignt editor SQL when querying from the entity. It is recommended to prefix this with an acronym indicating the data source to distinguish similar table names from other data sources. For example, gtmhub_issues when we are querying the issues entity from the Quantive Results Data app)

schema.types.staticFields

The list of data fields to pull from the collection of results. At least one field is required but multiple can be specified where needed.

schema.types.staticFields.name

    name: "term"

The JavaScript notation to get to the field that you want within the JSON object

schema.types.staticFields.title

    title: "Term"

The name of the field (also used to determine the table column name) that will be visible UI.

schema.types.staticFields.type

    type: "string"

The data type for the table column where data for this field is stored. Supported options are:

  • string
  • double
  • integer
  • date
  • long

schema.types.download

The download instructions for this entity. This defines what API call the Data app will make to fetch the items for that type.

schema.types.download.uri

  uri: "/glossary"

This is the api ednpoint uri. It is always append to the base URL to create the full API call

schema.types.download.verb

  verb: GET

Usually a GET, but may be another HTTP verb depending on your REST API.

schema.types.download.headers

  headers:
      accept: "application/json"

All necessary headers for the call. This collection usually includes authorization header information when your REST API requires it. See Using connection parameters to store API tokens for more information on how you can ask users to provide an API token when setting up your Data app, and how you can use it in your YAML headers collection.

schema.types.download.responses

The responses object enables you to describe how your REST API JSON response looks like, and which elemnts from it contain the data you are interested in consuming.

schema.types.download.responses.collection

    collection: "glossary"

If the REST API response contains multiple collections, specify which one contains the data for this type. If the root of the response is the list of items (i.e. the response is a JSON array) then leave this property with no value.

schema.types.download.paging

If the REST API endpoint implements paging, you must describe how the paging mechanism should work. The paging object has the following properties:

  • kind - it's always custom-rest
  • skipParamName - the name of the skip parameter in your REST API (for example, skip, fetch). The default is "skip".
  • takeParamName - the name of the take parameter in your REST API (for example, take, top, limit). The default is "take".
  • skip - how many items to skip in a single paged request. The default is 0.
  • take - how many items to take in a single paged request. The default is 50.
  • skipIncrementBy - hwo to calculate the skip parameter on each consecutive request. The default is skip += take