super.json
super.json
is the main Superface configuration file, located by default in the superface
folder under your project root, but it can also be passed as the superJson
property during SDK initialization. It specifies which profiles, maps, and providers are used, and their configuration (e.g. API credentials).
It is not required (in most cases) in order to use Superface, but you may still find it useful as your project grows in size and complexity, or you wish to use more advanced features. See Advanced Usage for more details.
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
{
"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:
- a semantic version string
- a file URI string, which is an absolute or relative path prepended by
file:
{
"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 haveproviderFailover
set totrue
providers
: an array of ProfileProviderSettings objects or URI strings, used for configuring providers for the profile. Not to be confused with top-level Providers recorddefaults
: a record of defaults for the use-case, key is use-case name, value is UsecaseDefaults object
{
"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 inputproviderFailover
: a boolean specific whether provider failover should be allowed for the use-case. Defaults tofalse
{
"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
:
defaults
: a record of defaults per use-case, key is use-case name and value is a ProfileProviderDefaults object
{
"profiles": {
"myprofile": {
"providers": {
"provider-one": {
"file": "path/to/provider.json",
"defaults": {
"MyUseCase": {
// ProfileProviderDefaults
}
}
}
}
}
}
}
{
"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 inputretryPolicy
: a RetryPolicy object
{
"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
orcircuit-breaker
maxContiguousRetries
: maximum number of retry attempts, positive integer, default 5requestTimeout
: timeout after which a request fails, positive integer, milliseconds, default 30000backoff
: either stringexponential
or an object with following properties:kind
: stringexponential
start
: the initial delay time, optional, positive integer, milliseconds, default 2000factor
: the factor by which is the delay time multiplied, optional, positive integer, default 2
{
"profiles": {
"myprofile": {
"providers": {
"provider-one": {
"defaults": {
"MyUseCase": {
"retryPolicy": {
"kind": "circuit-breaker",
"maxContiguousRetries": 3,
"requestTimeout": 60000,
"backoff": {
"kind": "exponential",
"start": 1000,
"factor": 3
}
}
}
}
}
}
}
}
}
{
"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.
{
"providers": {
"provider-one": "file:path/to/provider.json",
"provider-two": {
// ProviderSettings
}
}
}
ProviderSettings
The ProviderSettings object has following optional properties:
file
: a file URI stringsecurity
: an array of SecurityValues objects
{
"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 usernamepassword
: string containing password
Digest Auth
Digest Auth uses provided username and password to handle digest flow as per RFC 7616. Obtained credentials are cached inside SuperfaceClient
instance and reused if possible.
username
: string containing usernamepassword
: 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
{
"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"
}
]
}
}