Skip to content

Latest commit

 

History

History
58 lines (40 loc) · 5.29 KB

response-templates.md

File metadata and controls

58 lines (40 loc) · 5.29 KB

Response Templates

Overview

Response templates are used to override the default values sent in response to consumer calls to an API. They can be implemented for all v4 API HTTP entrypoints:

  • HTTP GET
  • HTTP POST
  • HTTP proxy
  • SSE
  • Webhook
  • WebSocket

{% hint style="info" %} As of Gravitee 4.3, response templates cannot override message-level errors or be applied to TCP proxy entrypoints. {% endhint %}

Response template overrides are triggered by error keys, which are specific to policies. Responses can be templatized if the errors raised during the request/response phase(s) are associated with a policy whose policy keys can be overridden. Each response template defines the new values to be returned for one or more status codes when the template is triggered.

Configuration

Prerequisites

Prior to defining a response template, verify:

  • Which policies have been applied to the API. This can be viewed in the API's plan.
  • Which error keys can be overridden per policy associated with your API.

Below are the policy error keys that you can override by configuring response templates:

KeyPolicy
API_KEY_MISSINGAPI key
API_KEY_INVALIDAPI key
QUOTA_TOO_MANY_REQUESTSRate limiting
RATE_LIMIT_TOO_MANY_REQUESTSRate limiting
REQUEST_CONTENT_LIMIT_TOO_LARGERequest content limit
REQUEST_CONTENT_LIMIT_LENGTH_REQUIREDRequest content limit
REQUEST_TIMEOUTMock, Callout HTTP, Request validation
REQUEST_VALIDATION_INVALIDRequest validation
RESOURCE_FILTERING_METHOD_NOT_ALLOWEDResource filtering
RBAC_INVALID_USER_ROLESRole-based access control
RESOURCE_FILTERING_FORBIDDENResource filtering
RBAC_FORBIDDENRole-based access control
RBAC_NO_USER_ROLERole-based access control
OAUTH2_MISSING_SERVEROAuth2
OAUTH2_MISSING_HEADEROAuth2
OAUTH2_MISSING_ACCESS_TOKENOAuth2
OAUTH2_INVALID_ACCESS_TOKENOAuth2
OAUTH2_INSUFFICIENT_SCOPEOAuth2
OAUTH2_INVALID_SERVER_RESPONSEOAuth2
OAUTH2_SERVER_UNAVAILABLEOAuth2
HTTP_SIGNATURE_INVALID_SIGNATUREHTTP Signature
JWT_MISSING_TOKENJWT
JWT_INVALID_TOKENJWT
JSON_INVALID_PAYLOADJSON validation
JSON_INVALID_FORMATJSON validation
JSON_INVALID_RESPONSE_PAYLOADJSON validation
JSON_INVALID_RESPONSE_FORMATJSON validation
GATEWAY_INVALID_REQUESTAll
GATEWAY_INVALID_RESPONSEAll
GATEWAY_OAUTH2_ACCESS_DENIEDAll
GATEWAY_OAUTH2_SERVER_ERRORAll
GATEWAY_OAUTH2_INVALID_CLIENTAll
GATEWAY_MISSING_SECURITY_PROVIDERAll
GATEWAY_PLAN_UNRESOLVABLEAll
GATEWAY_POLICY_INTERNAL_ERRORAll

Create a response template

When creating response templates, you can define:

  • Multiple templates for one API (for multiple policies and/or multiple error keys sent by the same policy)
  • Multiple template definitions for the same error key in a single template (for different content types or status codes)

To configure a response template:

  1. Log in to your APIM Management Console

  2. Select APIs from the left nav

  3. Select your API from the list

  4. Select Entrypoints from the inner left nav

  5. Click on the Response Templates header

  6. Click on the Add new Response Template button

  7. Customize the Create a new Response Template form

    Configure a new response template

    • Template key: Choose the template key via the Template key drop-down.
    • Accept header to match: Specify the requests header that should trigger use of the response template. The default value is */*. To send the template override values only for JSON or XML requests, specify JSON or XML.
    • Status code: Specify the status code that to send to the API consumer via the Status code drop-down.
    • Specify the override values to send to the API consumer. These can either be:
      • One or more HTTP headers to include in the response
      • A response template body

  8. Click Create