ORDS Configuration options: about HTTP error responses

by

Reading docs can be hard

We send you poor folks to our documentation, and sometimes, it’s a section we haven’t reviewed in quite some time! I don’t think this is specific to any one organization. But over the years, details get lost, forgotten, or stored in an obscure guide section, only to be reviewed once in a blue moon.

Below is a perfect example. This week, while attempting to assist one of our support engineers, I directed them (and the customer) to Chapter 2.18 of our ORDS Developer’s Guide. In it, we discuss the various configuration settings for how ORDS can return HTTP error responses (HTML, JSON, or Auto).

However, we don’t explicitly tell you how to change these settings or where to look 😭. I desperately need context and references because I find tech challenging to understand. To me, that’s a big part of providing users with context.

Current version

Chapter 2.18 About HTTP Error Responses (click to expand)

ORDS can now generate HTTP error responses in JSON or HTML format. Prior to ORDS release 20.4, only HTML responses were supported. To preserve the backward compatibility, by default, ORDS attempts to automatically determines the best format to render the error responses.

You can configure error.responseFormat setting and force ORDS to always render the error responses in either HTML or JSON format.

2.18.1 About error.responseFormat

The error.responseFormat setting is a global setting that supports the following values:

  • html – Force all error responses to be in HTML format.
  • json – Force all error responses to be in JSON format.
  • auto (default value) – Automatically determine most appropriate format for a request. 
2.18.1.1 HTML Mode

When error.responseFormat value is set to html, all the error responses are rendered in HTML format. This setting can be used to match the behaviour of ORDS 20.3.1 and prior releases. The HTML format displays properly in web-browsers. However, for non-human clients, HTML format is verbose and challenging to parse.

2.18.1.2 json Mode

When error.responseFormat value is set to json, all the error responses are rendered in JSON format. The JSON format complies with the Problem Details for HTTP APIs standard. The JSON format is terse, and straightforward for non-human clients to parse. However, it does not display properly in browsers and is not user friendly for non-technical users.

2.18.1.3 auto Mode

The default value for error.responseFormat is auto. When this value is configured, ORDS applies the following rules and automatically chooses the most appropriate format to use: 

If the client supplies a User-Agent header whose value starts with curl/, then the response must be in JSON format. cURL is a popular command line tool for making the HTTP requests. The terser JSON format is more readable in a command line environment. If none of the preceding rules apply, then the response will be in HTML format. See Also:cURL

If the client supplies an Accept request header, where application/json or application/problem+json is the most preferred media type, then the response must be in JSON format.

If the client supplies an Accept request header where text/html is the most preferred media type, then the response must be in HTML format.

If the client supplies a X-Requested-With header, then the response must be in JSON format. Presence of this header indicates that the request is initiated from the JavaScript code and so JSON would be the appropriate response format.

If the client supplies an Origin header, then the response must be in JSON format. Presence of this header indicates that the request is initiated from the JavaScript code and so JSON would be the appropriate response format.

There is one exception to this rule, if the request method is POST and the Content-Type of the request is application/x-www-form-urlencoded, then the response will be in HTML format.

Proposed version/updates

2.18 About HTTP Error Responses

You may configure ORDS to generate HTTP error responses exclusively in HTML or JSON format (the default setting is “Auto”). You can modify the error response format by issuing the following ORDS CLI commands:

FormatCommand
HTMLords config set error.responseFormat html
JSONords config set error.responseFormat json
Auto (default)ords config set error.responseFormat auto

NOTE: Prior to ORDS 20.4, only HTML responses were supported. To preserve this backward compatibility, by default (i.e., via the Auto setting), ORDS attempts to automatically determine the best format to render error responses.

2.18.1 About the error.response Format

The error.responseFormat setting is a global1 setting that supports the following values:

  • HTML – error responses are returned in HTML format.
  • JSON – error responses are returned in JSON format.
  • Auto (default setting) – Automatically determines the most appropriate format for error responses.

You may use the following ORDS command line command to review your existing configuration settings:

ords config list --include-defaults

1Global settings are those settings found in the /[your ORDS configuration folder]/global/settings.xml file. These settings apply to all ORDS instances, regardless of whether they are installed at the Container database (CDB) or Pluggable database (PDB) level.

NOTE: An ORDS best practice is to install ORDS at the PDB level. This configuration supports High-Availability, Fast Failover, rolling updates, etc. See our Best Practices page for more details.

2.18.1.1 HTML Mode

ORDS will render error responses in HTML format when you set the error.responseFormat value to html. You may use this setting to match the behavior of ORDS 20.3.1 and prior releases. The HTML format displays properly in web browsers. However, the HTML format is verbose for non-human clients and may be challenging to parse. The JSON format may be a better alternative for these applications.

2.18.1.2 JSON Mode

ORDS will render error responses in JSON format when you set the error.responseFormat value to json. The JSON format complies with the Problem Details for HTTP APIs standard2.

While the JSON format may not display correctly in browsers and can be challenging for non-technical users to decipher. Although it is terse and straightforward for non-human clients to parse. An exception to this may be in a command line environment; tools such as curl3 make inspecting JSON simple.

2Learn more: RFC 7807 Problem Details for HTTP APIs
3Download curl

2.18.1.3 Auto Mode

The default value for ORDS’ error.responseFormat setting is auto. When auto is selected, ORDS automatically applies rules according to various conditions and returns responses in the appropriate format. The following conditions and their dispositions are below:

HTML

ORDS will return the HTML format when the client supplies an…

  • Accept request header where text/html is the “most preferred” media type.4
  • Origin header and request method is a POST and Content-Type is application/x-www-form-urlencoded.
JSON

ORDS will return the JSON format when the client supplies an…

  • Accept request header and application/json or application/problem+json is the “most preferred” media type.4
  • X-Requested-With request header.5,6
  • User-Agent header whose value starts with curl/.
  • Origin request header.5
    • EXCEPTION: Responses will be rendered in the HTML format when the request method is POST and Content-Type is application/x-www-form-urlencoded.

4About q-factor weighting
5The presence of this header indicates the request was initiated via JavaScript code. Accordingly, JSON is the most appropriate response format.
6When performing an asynchronous HTTP (Ajax) request, the header X-Requested-With: XMLHttpRequest is always added. See Settings > headers for details.

Thoughts?

So what do you think? Is this format helpful? Does it read and flow better? My goal is to give you exactly what you need upfront. Then, if you choose, you can explore further. Are the references helpful? Are you “learning as you’re learning”? I wish all of life were like this; you get a glimpse of the levels upon levels of context.

Welp, this doc bug has been filed! On to the next one! Until next time 😊.

Follow

And don’t forget to follow, like, subscribe, share, taunt, troll, or stalk me!

Leave a Comment