Skip to main content

super.json

super.json is the main Superface configuration file, located in superface folder by default. It specifies which profiles, maps, and providers are used.

Anatomy​

At the top level, the super.json file consists of two sections: profiles and providers. The profiles section contains a list of installed profiles, their versions or file locations, and default values. The providers section contains a list of installed providers and their credentials.

Example​

superface/super.json
{
  "profiles": {
    // Profiles
    "myprofile1": "1.0.0", // Semver shorthand
    "myprofile2": "file:path/to/my/profile.supr", // File URI shorthand
    "myprofile3": {
      // ProfileSettings
      "version": "1.0.0",
      "priority": ["provider-one", "provider-two"],
      "defaults": {
        "MyUseCase": {
          // UsecaseDefaults
          "input": {
            "someInputProperty": 42
          },
          "providerFailover": true
        }
      },
      "providers": {
        "provider-one": {
          // ProfileProviderSettings
          "file": "path/to/provider.json",
          "defaults": {
            "MyUseCase": {
              // ProfileProviderDefaults
              "input": {
                "someInputProperty": 43
              },
              "retryPolicy": {
                // RetryPolicy
                "kind": "circuit-breaker",
                "maxContiguousRetries": 3,
                "requestTimeout": 60000,
                "backoff": {
                  "kind": "exponential",
                  "start": 1000,
                  "factor": 3
                }
              }
            }
          }
        },
        "provider-two": "file:path/to/provider.json" // File URI shorthand
      }
    }
  },
  "providers": {
    // Providers
    "provider-one": "file:path/to/provider.json", // File URI shorthand
    "provider-two": {
      // ProviderSettings
      "file": "path/to/provider.json",
      "security": [
        // SecurityValues
        {
          "id": "my-authentication",
          "apikey": "my-api-key"
        }
      ]
    }
  }
}

Profiles​

The profiles section consists of a record of all installed profiles. The key is the name of the profile and value is either a shorthand or a ProfileSettings object. There are two options for the shorthand:

superface/super.json
{
  "profiles": {
    "myprofile1": "1.0.0",
    "myprofile2": "file:path/to/profile.supr",
    "myprofile3": {
      // ProfileSettings
    }
  }
}

ProfileSettings​

The ProfileSettings object contains either file or version property, analogous to the shortcut strings above (the file: prefix is optional in this case) and following optional properties:

  • priority: an array of strings containing provider names in desired order for failover. If omitted, it is constructed from the order of providers in this file that have providerFailover set to true
  • providers: an array of ProfileProviderSettings objects or URI strings, used for configuring providers for the profile. Not to be confused with top-level Providers record
  • defaults: a record of defaults for the use-case, key is use-case name, value is UsecaseDefaults object
superface/super.json
{
  "profiles": {
    "myprofile": {
      "version": "1.0.0",
      "priority": ["provider-one", "provider-two"],
      "defaults": {
        "MyUseCase": {
          // UsecaseDefaults
        }
      },
      "providers": {
        "provider-one": {
          // ProfileProviderSettings
        },
        "provider-two": "file:path/to/provider.json"
      }
    }
  }
}

UsecaseDefaults​

UsecaseDefaults specifies default values for a use-case for all providers. The key is use-case's name and the value is an object with following optional properties:

  • input: an object providing default values according to use-case's input
  • providerFailover: a boolean specific whether provider failover should be allowed for the use-case. Defaults to false
superface/super.json
{
  "profiles": {
    "myprofile": {
      "defaults": {
        "MyUseCase": {
          "input": {
            "someInputProperty": 42
          },
          "providerFailover": true
        }
      }
    }
  }
}

ProfileProviderSettings​

ProfileProviderSettings object defines profile-specific configuration of providers. The provider definition can be either a file path (in file property), or a specific variant and revision (with mapVariant and mapRevision). It can also contain the optional property defaults:

superface/super.json
{
  "profiles": {
    "myprofile": {
      "providers": {
        "provider-one": {
          "file": "path/to/provider.json",
          "defaults": {
            "MyUseCase": {
              // ProfileProviderDefaults
            }
          }
        }
      }
    }
  }
}
superface/super.json
{
  "profiles": {
    "myprofile": {
      "providers": {
        "provider-two": {
          "mapVariant": "my-variant",
          "mapRevision": "3",
          "defaults": {
            "MyUseCase": {
              // ProfileProviderDefaults
            }
          }
        }
      }
    }
  }
}

ProfileProviderDefaults​

ProfileProviderDefaults is an object with following optional properties:

  • input: an object providing default values according to the use-case's input
  • retryPolicy: a RetryPolicy object
superface/super.json
{
  "profiles": {
    "myprofile": {
      "providers": {
        "provider-one": {
          "defaults": {
            "MyUseCase": {
              "input": {
                "someInputProperty": 42
              },
              "retryPolicy": {
                // RetryPolicy
              }
            }
          }
        }
      }
    }
  }
}

RetryPolicy​

RetryPolicy is used for setting up retry policy for a provider and use-case. There are currently two types of retry policy, none or circuit-breaker. When using none, no retry is attempted. When using circuit-breaker, several attempts are made with back-off. Following properties are used to configure the policy (all optional except kind). When using default values, none or circuit-breaker string can be used as shorthand instead of the object.

  • kind: none or circuit-breaker
  • maxContiguousRetries: maximum number of retry attempts, positive integer, default 5
  • requestTimeout: timeout after which a request fails, positive integer, milliseconds, default 30000
  • backoff: either string exponential or an object with following properties:
    • kind: string exponential
    • start: the initial delay time, optional, positive integer, milliseconds, default 2000
    • factor: the factor by which is the delay time multiplied, optional, positive integer, default 2
superface/super.json
{
  "profiles": {
    "myprofile": {
      "providers": {
        "provider-one": {
          "defaults": {
            "MyUseCase": {
              "retryPolicy": {
                "kind": "circuit-breaker",
                "maxContiguousRetries": 3,
                "requestTimeout": 60000,
                "backoff": {
                  "kind": "exponential",
                  "start": 1000,
                  "factor": 3
                }
              }
            }
          }
        }
      }
    }
  }
}
superface/super.json
{
  "profiles": {
    "myprofile": {
      "providers": {
        "provider-one": {
          "defaults": {
            "MyUseCase": {
              "retryPolicy": "circuit-breaker"
            }
          }
        }
      }
    }
  }
}

Providers​

The providers section consists of a record of all used providers. The key is the name of the provider and the value is either a file URI (with file: prefix) or a ProviderSettings object.

superface/super.json
{
  "providers": {
    "provider-one": "file:path/to/provider.json",
    "provider-two": {
      // ProviderSettings
    }
  }
}

ProviderSettings​

The ProviderSettings object has following optional properties:

superface/super.json
{
  "providers": {
    "myprovider": {
      "file": "path/to/provider.json",
      "security": [
        {
          // SecurityValues
        }
      ]
    }
  }
}

SecurityValues​

SecurityValues is a union of several types of security configuration objects: API Key, Basic Auth or Bearer Token. Values starting with $ will be replaced with environment variables with the name following $. All of them have a property in common:

  • id: identifier of the security scheme, referenced in map

API Key​

API key uses provided API key in a header, body, path or query string (specified in provider.json)

  • apikey: string containing API key

Basic Auth​

Basic Auth uses provided username and password and sends them base64 encoded in Authorization header as per RFC 7617

  • username: string containing username
  • password: string containing password

Bearer Token​

Bearer Token uses provided token and sends it in Authorization header as per RFC 6750

  • token: string containing bearer token
superface/super.json
{
  "providers": {
    "file": "path/to/provider.json",
    "security": [
      {
        "id": "first",
        "apikey": "my-api-key"
      },
      {
        "id": "second",
        "username": "$MY_NAME", // Value of environment variable MY_NAME will be used here
        "password": "$MY_PASSWORD" // Value of environment variable MY_PASSWORD will be used here
      },
      {
        "id": "third",
        "token": "my-bearer-token"
      },
      {
        "id": "fourth",
        "digest": "my-digest"
      }
    ]
  }
}