Skip to content

Add API Backend form help text

Jump to bottom Edit New page
Aseem Shakuntal edited this page Oct 18, 2015 · 21 revisions

This page contains a section for each field on the Add API Backend form. Within each section is existing or suggested help text.

Name

  • Current: API's name
  • Proposed: Enter a name which describes your API the best way.

Backend

API Umbrella

Define the server where the API is hosted. Multiple servers can be defined to perform load balancing.

Apinf

  • Current:
  • Proposed:

Backend protocol

  • Current: Choose backend server protocol
  • Proposed: Choose the protocol used by your API (e.g. http or https)

Servers

  • Current: Define the server where the API is hosted. Host field is for URL of your API without 'http(s)'
  • Proposed:

Host

  • Proposed: Host where your API is located.

API Umbrella

Define the host that we will listen for, and then the host the API backend is listening for.

Apinf

  • Current:
  • Proposed:

Port

  • Current:
  • Proposed:

Host

  • Current:
  • Proposed:

Frontend host

  • Current: Define the server where the API Umbrella instance is hosted. If API Umbrella installed locally, enter localhost as your Backend host.
  • Proposed:

Backend host

  • Current: Define the server where the API is hosted.
  • Proposed:

Matching URL Prefixes

API Umbrella

What URL prefixes should be routed to this backend?

Apinf

  • Current:
  • Proposed:

Url matches

Matching URL Prefixes in API Umbrella

API Umbrella

Tip: We recommend using trailing slashes when configuring these URL prefixes when possible (for example, using /wind/ instead of /wind). While not necessary, this helps prevent future overlapping conflicts (for example, if someone later wants to set up /windmill/).

Example: Incoming Frontend Request: http://api.data.govexample.json?param=value Outgoing Backend Request: http://api.data.govexample.json?param=value

Apinf

  • Current:

Tip: We recommend using trailing slashes when configuring these URL prefixes when possible (for example, using /wind/ instead of /wind). While not necessary, this helps prevent future overlapping conflicts (for example, if someone later wants to set up /windmill/).

Example: Incoming Frontend Request: http://api.data.govexample.json?param=value Outgoing Backend Request: http://api.data.govexample.json?param=value

  • Proposed:

Frontend prefix

  • Current:
  • Proposed:

Backend prefix

  • Current:
  • Proposed:

Documentation

  • Current:
  • Proposed:

Documentation link

  • Current:
  • Proposed:

Upload documentation

  • Current:
  • Proposed:

Documentation Configuration File

  • Current:
  • Proposed:

Create new documentation

  • Current:
  • Proposed:

Global Request Settings

  • Current:
  • Proposed:

Append query string parameters

API Umbrella

Placeholder text:

param1=value&param2=value

Apinf

  • Current:
  • Proposed:

Set headers

API Umbrella

Field name: Set Request Headers

Placeholder text:

X-Example-Header: value

Apinf

  • Current:
  • Proposed:

HTTP basic authentication

API Umbrella

Placeholder text:

username:password

Apinf

  • Current:
  • Proposed:

HTTPS requirements

API Umbrella

Define header values that will be set in the response regardless of whether the header is already set in the response.

For example, to set default CORS headers on all responses that don"t explicitly set their own CORS headers:

Access-Control-Allow-Origin: *

Select input options

  • key -- example
    • value -- example
  • Inherit (default - required & return message)
    • [default?]
  • Required & return message - HTTP requests will receive a message to use HTTPS
    • required_return_error
  • Required & return redirects - HTTP requests will be redirected to HTTPS
    • required_return_redirect
  • Transitionary & return message - Optional for existing API keys, required for new API keys
    • transition_return_error
  • Transitionary & return redirects - Optional for existing API keys, required for new API keys
    • transition_return_redirect
  • Optional - HTTPS is optional
    • optional

Apinf

  • Current:
  • Proposed:

API Key Checks

API Umbrella

Selection options (key/value)

  • key
    • value
  • Inherit (default - required)
    • [default?]
  • Required - API keys are mandatory
    • [required?]
  • Disabled - API keys are optional
    • value

Apinf

  • Current:
  • Proposed:

Required roles

  • Current:
  • Proposed:

Via HTTP header

  • Current:
  • Proposed:

Via GET query parameter

  • Current:
  • Proposed:

Rate limit mode

API Umbrella

Select options

  • key
    • value
  • Default rate limits
    • [default?]
  • Custom rate limits
    • custom
  • Unlimited requests
    • unlimited

Apinf

  • Current:
  • Proposed:

Default response headers

API Umbrella

Help text:

Define header values that will be set in the response regardless of whether the header is already set in the response.

For example, to set default CORS headers on all responses that don"t explicitly set their own CORS headers:

Access-Control-Allow-Origin: *

Placeholder text:

X-Example-Header: value

Apinf

Not currently implemented (Issue #503)

Override Response Headers

API Umbrella

Help text:

Define header values that will be set in the response regardless of whether the header is already set in the response.

For example, to force CORS headers on all responses:

Access-Control-Allow-Origin: *

Placeholder text:

X-Example-Header: value

Apinf

Not currently implemented (Issue #504)

Advanced Requests Rewriting

Api Umbrella

Modify the incoming request's URL or headers before passing it to the backend.

Apinf

  • Current:
  • Proposed:

Rewrite

  • Current:
  • Proposed:

Matcher type

  • Current:
  • Proposed:

HTTP method

  • Current:
  • Proposed:

Frontend matcher

  • Current:
  • Proposed:

Backend replacement

  • Current:
  • Proposed:

Advanced Settings

  • Current:
  • Proposed:

Balance algorithm

API Umbrella

Selection options

  • key example
    • value example
  • Least Connections
    • least_conn
  • Round Robin
  • round_robin
  • Source IP Hash
    • ip_hash

Apinf

  • Current:
  • Proposed:

Error templates

  • Current:
  • Proposed:

JSON

API Umbrella

A Handlebars template of the JSON error response. Available Handlebars variables are defined below in the Error Data section.

Default template:

{
  "error": {
    "code": {{code}},
    "message": {{message}}
  }
}

Apinf

  • Current:
  • Proposed:

XML

API Umbrella

A Handlebars template of the XML error response. Available Handlebars variables are defined below in the Error Data section.

Default template:

<?xml version="1.0" encoding="UTF-8"?>
<response>
 <error>
    <code>{{code}}</code>
    <message>{{message}}</message>
  </error>
</response>

Apinf

  • Current:
  • Proposed:

CSV

API Umbrella

A Handlebars template of the CSV error response. Available Handlebars variables are defined below in the Error Data section.

Default template:

Error Code,Error Message
{{code}},{{message}}

Apinf

  • Current:
  • Proposed:
Add a custom footer
Add a custom sidebar
Clone this wiki locally