Skip to main content

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​

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

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 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"
      }
    ]
  }
}