Get a service descriptor

{
  "type": "object",
  "description": "An otoroshi service descriptor. Represent a forward HTTP call on a domain to another location with some optional api management mecanism",
  "required": [
    "buildMode",
    "domain",
    "enabled",
    "enforceSecureCommunication",
    "env",
    "forceHttps",
    "groups",
    "id",
    "maintenanceMode",
    "name",
    "privateApp",
    "root",
    "subdomain",
    "targets"
  ],
  "properties": {
    "Canary": {
      "type": "object",
      "description": "The configuration of the canary mode for a service descriptor",
      "required": [
        "enabled",
        "root",
        "targets",
        "traffic"
      ],
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Use canary mode for this service"
        },
        "root": {
          "type": "string",
          "description": "Otoroshi will append this root to any target choosen. If the specified root is '/api/foo', then a request to https://yyyyyyy/bar will actually hit https://xxxxxxxxx/api/foo/bar"
        },
        "targets": {
          "type": "array",
          "description": "The list of target that Otoroshi will proxy and expose through the subdomain defined before. Otoroshi will do round-robin load balancing between all those targets with circuit breaker mecanism to avoid cascading failures",
          "items": {
            "type": "object",
            "description": "A Target is where an HTTP call will be forwarded in the end from a service domain",
            "required": [
              "host",
              "scheme"
            ],
            "properties": {
              "host": {
                "type": "string",
                "format": "hostname",
                "description": "The host on which the HTTP call will be forwarded. Can be a domain name, or an IP address. Can also have a port"
              },
              "scheme": {
                "type": "string",
                "description": "The protocol used for communication. Can be http or https"
              }
            }
          }
        },
        "traffic": {
          "type": "integer",
          "format": "int32",
          "description": "Ratio of traffic that will be sent to canary targets."
        }
      }
    },
    "additionalHeaders": {
      "type": "object",
      "description": "Specify headers that will be added to each client request. Useful to add authentication"
    },
    "api": {
      "type": "object",
      "description": "The Open API configuration for your service (if one)",
      "required": [
        "exposeApi"
      ],
      "properties": {
        "exposeApi": {
          "type": "boolean",
          "description": "Whether or not the current service expose an API with an Open API descriptor"
        },
        "openApiDescriptorUrl": {
          "type": "string",
          "format": "uri",
          "description": "The URL of the Open API descriptor"
        }
      }
    },
    "authConfigRef": {
      "type": "string",
      "description": "A reference to a global auth module config"
    },
    "buildMode": {
      "type": "boolean",
      "description": "Display a construction page when a user try to use the service"
    },
    "chaosConfig": {
      "type": "object",
      "description": "Configuration for the faults that can be injected in requests",
      "required": [
        "enabled"
      ],
      "properties": {
        "badResponsesFaultConfig": {
          "type": "object",
          "description": "Config for bad requests injection fault",
          "required": [
            "ratio",
            "responses"
          ],
          "properties": {
            "ratio": {
              "type": "number",
              "format": "double",
              "description": "The percentage of requests affected by this fault. Value should be between 0.0 and 1.0"
            },
            "responses": {
              "type": "array",
              "description": "The possibles responses",
              "items": {
                "type": "object",
                "description": "An HTTP response that is not supposed to be returned by a service",
                "required": [
                  "status",
                  "body",
                  "headers"
                ],
                "properties": {
                  "body": {
                    "type": "string",
                    "description": "The body of the HTTP response"
                  },
                  "headers": {
                    "type": "object",
                    "description": "The HTTP headers of the response"
                  },
                  "status": {
                    "type": "integer",
                    "format": "int32",
                    "description": "The HTTP status for the response"
                  }
                }
              }
            }
          }
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether or not this config is enabled"
        },
        "largeRequestFaultConfig": {
          "type": "object",
          "description": "Config for large request injection fault",
          "required": [
            "additionalRequestSize",
            "ratio"
          ],
          "properties": {
            "additionalRequestSize": {
              "type": "integer",
              "format": "int32",
              "description": "The size added to the request body in bytes. Added payload will be spaces only."
            },
            "ratio": {
              "type": "number",
              "format": "double",
              "description": "The percentage of requests affected by this fault. Value should be between 0.0 and 1.0"
            }
          }
        },
        "largeResponseFaultConfig": {
          "type": "object",
          "description": "Config for large response injection fault",
          "required": [
            "additionalResponseSize",
            "ratio"
          ],
          "properties": {
            "additionalRequestSize": {
              "type": "integer",
              "format": "int32",
              "description": "The size added to the response body in bytes. Added payload will be spaces only."
            },
            "ratio": {
              "type": "number",
              "format": "double",
              "description": "The percentage of requests affected by this fault. Value should be between 0.0 and 1.0"
            }
          }
        },
        "latencyInjectionFaultConfig": {
          "type": "object",
          "description": "Config for large latency injection fault",
          "required": [
            "from",
            "ratio",
            "to"
          ],
          "properties": {
            "from": {
              "type": "integer",
              "format": "int32",
              "description": "The start range of latency added to the request"
            },
            "ratio": {
              "type": "number",
              "format": "double",
              "description": "The percentage of requests affected by this fault. Value should be between 0.0 and 1.0"
            },
            "to": {
              "type": "integer",
              "format": "int32",
              "description": "The end range of latency added to the request"
            }
          }
        }
      }
    },
    "clientConfig": {
      "type": "object",
      "description": "The configuration of the circuit breaker for a service descriptor",
      "required": [
        "backoffFactor",
        "callTimeout",
        "globalTimeout",
        "maxErrors",
        "retries",
        "retryInitialDelay",
        "sampleInterval",
        "useCircuitBreaker"
      ],
      "properties": {
        "backoffFactor": {
          "type": "integer",
          "format": "int32",
          "description": "Specify the factor to multiply the delay for each retry"
        },
        "callTimeout": {
          "type": "integer",
          "format": "int32",
          "description": "Specify how long each call should last at most in milliseconds"
        },
        "globalTimeout": {
          "type": "integer",
          "format": "int32",
          "description": "Specify how long the global call (with retries) should last at most in milliseconds"
        },
        "maxErrors": {
          "type": "integer",
          "format": "int32",
          "description": "Specify how many errors can pass before opening the circuit breaker"
        },
        "retries": {
          "type": "integer",
          "format": "int32",
          "description": "Specify how many times the client will try to fetch the result of the request after an error before giving up."
        },
        "retryInitialDelay": {
          "type": "integer",
          "format": "int32",
          "description": "Specify the delay between two retries. Each retry, the delay is multiplied by the backoff factor"
        },
        "sampleInterval": {
          "type": "integer",
          "format": "int32",
          "description": "Specify the sliding window time for the circuit breaker in milliseconds, after this time, error count will be reseted"
        },
        "useCircuitBreaker": {
          "type": "boolean",
          "description": "Use a circuit breaker to avoid cascading failure when calling chains of services. Highly recommended !"
        }
      }
    },
    "clientValidatorRef": {
      "type": "string",
      "description": "A reference to validation authority"
    },
    "cors": {
      "type": "object",
      "description": "The configuration for cors support",
      "required": [
        "allowCredentials",
        "allowHeaders",
        "allowMethods",
        "allowOrigin",
        "enabled",
        "excludedPatterns",
        "exposeHeaders",
        "maxAge"
      ],
      "properties": {
        "allowCredentials": {
          "type": "boolean",
          "description": "Allow to pass credentials"
        },
        "allowHeaders": {
          "type": "array",
          "description": "The cors allowed headers",
          "items": {
            "type": "string"
          }
        },
        "allowMethods": {
          "type": "array",
          "description": "The cors allowed methods",
          "items": {
            "type": "string"
          }
        },
        "allowOrigin": {
          "type": "string",
          "description": "The cors allowed origin"
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether or not cors is enabled"
        },
        "excludedPatterns": {
          "type": "array",
          "description": "The cors excluded patterns",
          "items": {
            "type": "string"
          }
        },
        "exposeHeaders": {
          "type": "array",
          "description": "The cors exposed header",
          "items": {
            "type": "string"
          }
        },
        "maxAge": {
          "type": "integer",
          "format": "int32",
          "description": "Cors max age"
        }
      }
    },
    "domain": {
      "type": "string",
      "description": "The domain on which the service is available."
    },
    "enabled": {
      "type": "boolean",
      "description": "Activate or deactivate your service. Once disabled, users will get an error page saying the service does not exist"
    },
    "enforceSecureCommunication": {
      "type": "boolean",
      "description": "When enabled, Otoroshi will try to exchange headers with downstream service to ensure no one else can use the service from outside"
    },
    "env": {
      "type": "string",
      "description": "The line on which the service is available. Based on that value, the name of the line will be appended to the subdomain. For line prod, nothing will be appended. For example, if the subdomain is 'foo' and line is 'preprod', then the exposed service will be available at 'foo.preprod.mydomain'"
    },
    "forceHttps": {
      "type": "boolean",
      "description": "Will force redirection to https:// if not present"
    },
    "groups": {
      "type": "array",
      "description": "Each service descriptor is attached to groups. A group can have one or more services. Each API key is linked to a group and allow access to every service in the group",
      "items": {
        "type": "string"
      }
    },
    "gzip": {
      "type": "object",
      "description": "Configuration for gzip of service responses",
      "required": [
        "blackList",
        "bufferSize",
        "chunkedThreshold",
        "compressionLevel",
        "enabled",
        "excludedPatterns",
        "whiteList"
      ],
      "properties": {
        "blackList": {
          "type": "array",
          "description": "Blacklisted mime types. Wildcard supported",
          "items": {
            "type": "string"
          }
        },
        "bufferSize": {
          "type": "integer",
          "format": "int64",
          "description": "Size of the GZip buffer"
        },
        "chunkedThreshold": {
          "type": "integer",
          "format": "int64",
          "description": "Threshold for chunking data"
        },
        "compressionLevel": {
          "type": "integer",
          "format": "int32",
          "description": "Compression level. From 0 to 9"
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether gzip compression is enabled or not"
        },
        "excludedPatterns": {
          "type": "array",
          "description": "Patterns that are excluded from gzipping",
          "items": {
            "type": "string"
          }
        },
        "whiteList": {
          "type": "array",
          "description": "Whitelisted mime types. Wildcard supported",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "headersVerification": {
      "type": "object",
      "description": "Specify headers that will be verified after routing."
    },
    "healthCheck": {
      "type": "object",
      "description": "The configuration for checking health of a service. Otoroshi will perform GET call on the URL to check if the service is still alive",
      "required": [
        "enabled"
      ],
      "properties": {
        "enabled": {
          "type": "boolean",
          "description": "Whether or not healthcheck is enabled on the current service descriptor"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "The URL to check"
        }
      }
    },
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "A unique random string to identify your service"
    },
    "ipFiltering": {
      "type": "object",
      "description": "The filtering configuration block for a service of globally.",
      "required": [
        "blacklist",
        "whitelist"
      ],
      "properties": {
        "blacklist": {
          "type": "array",
          "description": "Blacklisted IP addresses",
          "items": {
            "type": "string",
            "format": "ipv4"
          }
        },
        "whitelist": {
          "type": "array",
          "description": "Whitelisted IP addresses",
          "items": {
            "type": "string",
            "format": "ipv4"
          }
        }
      }
    },
    "jwtVerifier": {
      "type": "object"
    },
    "localHost": {
      "type": "string",
      "description": "The host used localy, mainly localhost:xxxx"
    },
    "localScheme": {
      "type": "string",
      "description": "The scheme used localy, mainly http"
    },
    "maintenanceMode": {
      "type": "boolean",
      "description": "Display a maintainance page when a user try to use the service"
    },
    "matchingHeaders": {
      "type": "object",
      "description": "Specify headers that MUST be present on client request to route it. Useful to implement versioning"
    },
    "matchingRoot": {
      "type": "string",
      "description": "The root path on which the service is available"
    },
    "metadata": {
      "type": "object",
      "description": "Just a bunch of random properties"
    },
    "name": {
      "type": "string",
      "description": "The name of your service. Only for debug and human readability purposes"
    },
    "overrideHost": {
      "type": "boolean",
      "description": "Host header will be overriden with Host of the target"
    },
    "privateApp": {
      "type": "boolean",
      "description": "When enabled, user will be allowed to use the service (UI) only if they are registered users of the private apps domain"
    },
    "privatePatterns": {
      "type": "array",
      "description": "If you define a public pattern that is a little bit too much, you can make some of public URL private again",
      "items": {
        "type": "string"
      }
    },
    "publicPatterns": {
      "type": "array",
      "description": "By default, every services are private only and you'll need an API key to access it. However, if you want to expose a public UI, you can define one or more public patterns (regex) to allow access to anybody. For example if you want to allow anybody on any URL, just use '/.*'",
      "items": {
        "type": "string"
      }
    },
    "redirectToLocal": {
      "type": "boolean",
      "description": "If you work locally with Otoroshi, you may want to use that feature to redirect one particuliar service to a local host. For example, you can relocate https://foo.preprod.bar.com to http://localhost:8080 to make some tests"
    },
    "redirection": {
      "type": "object",
      "description": "The configuration for redirection per service",
      "required": [
        "code",
        "enabled",
        "to"
      ],
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32",
          "description": "The http redirect code"
        },
        "enabled": {
          "type": "boolean",
          "description": "Whether or not redirection is enabled"
        },
        "to": {
          "type": "string",
          "description": "The location for redirection"
        }
      }
    },
    "root": {
      "type": "string",
      "description": "Otoroshi will append this root to any target choosen. If the specified root is '/api/foo', then a request to https://yyyyyyy/bar will actually hit https://xxxxxxxxx/api/foo/bar"
    },
    "secComExcludedPatterns": {
      "type": "array",
      "description": "URI patterns excluded from secured communications",
      "items": {
        "type": "string"
      }
    },
    "secComSettings": {
      "type": "object"
    },
    "sendOtoroshiHeadersBack": {
      "type": "boolean",
      "description": "When enabled, Otoroshi will send headers to consumer like request id, client latency, overhead, etc ..."
    },
    "statsdConfig": {
      "type": "object",
      "description": "The configuration for statsd metrics push",
      "required": [
        "datadog",
        "host",
        "port"
      ],
      "properties": {
        "datadog": {
          "type": "boolean",
          "description": "Datadog agent"
        },
        "host": {
          "type": "string",
          "description": "The host of the StatsD agent"
        },
        "port": {
          "type": "integer",
          "format": "int32",
          "description": "The port of the StatsD agent"
        }
      }
    },
    "subdomain": {
      "type": "string",
      "description": "The subdomain on which the service is available"
    },
    "targets": {
      "type": "array",
      "description": "The list of target that Otoroshi will proxy and expose through the subdomain defined before. Otoroshi will do round-robin load balancing between all those targets with circuit breaker mecanism to avoid cascading failures",
      "items": {
        "type": "object",
        "description": "A Target is where an HTTP call will be forwarded in the end from a service domain",
        "required": [
          "host",
          "scheme"
        ],
        "properties": {
          "host": {
            "type": "string",
            "format": "hostname",
            "description": "The host on which the HTTP call will be forwarded. Can be a domain name, or an IP address. Can also have a port"
          },
          "scheme": {
            "type": "string",
            "description": "The protocol used for communication. Can be http or https"
          }
        }
      }
    },
    "transformerRef": {
      "type": "string",
      "description": "A reference to a request transformer"
    },
    "userFacing": {
      "type": "boolean",
      "description": "The fact that this service will be seen by users and cannot be impacted by the Snow Monkey"
    },
    "xForwardedHeaders": {
      "type": "boolean",
      "description": "Send X-Forwarded-* headers"
    }
  }
}