Skip to main content

Add a new provider

Provider definition is a simple JSON description of a remote service running on the Internet. It declares:

  • the service provider name
  • where to find its servers
  • how to authenticate against those servers

This definition is later used by Map documents that create a request/response mapping between a specific capability and the provider's servers.

Basic Example​

{
  "name": "twilio",
  "services": [
    {
      "id": "default",
      "baseUrl": "https://api.twilio.com"
    }
  ],
  "defaultService": "default",
  "securitySchemes": [
    {
      "id": "basic",
      "type": "http",
      "scheme": "basic"
    }
  ]
}
Before you start

Please check our registry for existing providers before creating your own. Chances are the provider you're interested in was already defined by someone else.

In that case you can skip this guide & simply create a mapping for the capability using an existing provider.

Setup​

This guide assumes you have a project set up with Superface installed. If you need to set up a new project, please reference the Setup Guide.

Create new provider definition​

Choose the name​

Provider name serves primarily for identification. We recommend it to be as short as possible. It should also map the original provider's business name as closely as possible (e.g. if you're describing Facebook's API, just use facebook as the name).

Bootstrap via CLI​

The easiest way to bootstrap a new provider is using Superface CLI.

superface create --provider --providerName <provider-name>

Replace the <provider-name> in the command with the actual name you wish to use.

Running the above command creates a new JSON file at <provider-name>.provider.json and links the provider in the local super.json configuration file.

<provider-name>.provider.json
{
  "name": "<provider-name>",
  ...
}

Configure the services​

To be able to call the provider's web services, you need to first define them. Each service points to a specific base URL and has an identifier that is unique within the provider document.

<provider-name>.provider.json
{
  "name": "<provider-name>",
  "services": [
    {
      "id": "api",
      "baseUrl": "https://api.example.com"
    },
  ],
  ...
}

Replace the baseUrl value in the example with the actual base URL of the provider's API. You can also use your own id.

Some providers' APIs span across more URLs, or have different API versions hosted on different base URLs. In those cases, you should define multiple services.

Choose the default service​

Each provider needs one service to be selected as the default one. Choose one of the defined services and set its ID to defaultService parameter.

<provider-name>.provider.json
{
  "name": "<provider-name>",
  "services": [
    {
      "id": "api",
      "baseUrl": "https://api.example.com"
    }
  ],
  "defaultService": "api"
}

Note that api is the name of the service, thus can be used as a value for defaultService.

Configure authentication (security schemes)​

Optional

If the provider offers a public API that does not require any authentication, you can skip this step.

Define the expected form of authentication using security schemes. The actual credentials, tokens or keys will be provided later in runtime by the consumer either directly or via environment variables. Currently 3 types of security schemes are supported:

Basic Auth​

https://user:pass@api.example.com or Authorization: Basic <credentials> in headers

Use the following scheme with an arbitrary ID which can be referenced later from the mapping.

<provider-name>.provider.json
{
  "name": "<provider-name>",
  "services": [
    {
      "id": "api",
      "baseUrl": "https://api.example.com"
    }
  ],
  "defaultService": "api",
  "securitySchemes": [
    {
      "id": "<scheme-id>",
      "type": "http",
      "scheme": "basic"
    }
  ]
}

Replace the security scheme id value in the example with your own ID.

Bearer Token​

e.g. Authorization: Bearer <token> in headers

Use the following scheme with an arbitrary ID which can be referenced later from the mapping.

The value for bearerFormat is a hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.

<provider-name>.provider.json
{
  "name": "<provider-name>",
  "services": [
    {
      "id": "api",
      "baseUrl": "https://api.example.com"
    }
  ],
  "defaultService": "api",
  "securitySchemes": [
    {
      "id": "<scheme-id>",
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Bearer <token>"
    }
  ]
}

Replace the security scheme id value in the example with your own ID. Provide a better bearerFormat hint if necessary.

API Key in Headers or Query​

Use the following scheme with an arbitrary ID which can be referenced later from the mapping.

<provider-name>.provider.json
{
  "name": "<provider-name>",
  "services": [
    {
      "id": "api",
      "baseUrl": "https://api.example.com"
    }
  ],
  "defaultService": "api",
  "securitySchemes": [
    {
      "id": "<scheme-id>",
      "type": "apiKey",
      "in": "header", // supported values are "header" or "query"
      "name": "x-custom-header-name"
    }
  ]
}

Replace the security scheme id value in the example with your own ID. Choose the key location & name the parameter.

For key in header​

e.g. X-SECRET-KEY: <apikey> in headers

  • in must be set to header
  • name is the header name that holds the API key (e.g. X-SECRET-KEY)

For key in query​

e.g. https://api.example.com/?accessKey=<apikey>

  • in must be set to query
  • name is the query param name that holds the API key (e.g. accessKey)

Examples​