Configuration Properties

Halchemy takes a batteries-included approach to configuration. It starts with sensible defaults, and allows you to configure everything the way you like. This page shows you what you can change, and the next page show you how you can change them.

The Api object gives you the following configuration properties:

Setting	Description	Default
base_url	The base URL to the API you are working with. This default matches the default URL for a hypermea API running locally	http://localhost:2112
parameters_list_style	When creating a query string, this setting determines how lists are serialized. The options are: repeat_key, bracket, index, comma, pipe See Query String Parameters for more details.	repeat_key
etag_field	This is the field used to populate If-Match on a change request if ETag header is missing. This default is tuned for use with a hypermea API. See Optimistic Concurrency for more details.	_etag
headers	A set of default headers to include with each request. You can use this API property directly, and there are helper functions too. See Request Headers for more details.	(details below)
error_handling	Determines when exceptions are thrown/raised. There are two properties: raise_for_network_errors raise_for_status_codes	(details below)

Setting	Description	Default
baseUrl	The base URL to the API you are working with. This default matches the default URL for a hypermea API running locally	http://localhost:2112
parametersListStyle	When creating a query string, this setting determines how lists are serialized. The options are: repeat_key, bracket, index, comma, pipe See Query String Parameters for more details.	repeat_key
etagField	This is the field used to populate If-Match on a change request if ETag header is missing. This default is tuned for use with a hypermea API. See Optimistic Concurrency for more details.	_etag
headers	A set of default headers to include with each request. You can use this API property directly, and there are helper functions too. See Request Headers for more details.	(details below)
errorHandling	Determines when exceptions are thrown/raised. There are two properties: raiseForNetworkErrors raiseForStatusCodes	(details below)

Setting	Description	Default
base_url	The base URL to the API you are working with. This default matches the default URL for a hypermea API running locally	http://localhost:2112
parameters_list_style	When creating a query string, this setting determines how lists are serialized. The options are: repeat_key, bracket, index, comma, pipe See Query String Parameters for more details.	repeat_key
etag_field	This is the field used to populate If-Match on a change request if ETag header is missing. This default is tuned for use with a hypermea API. See Optimistic Concurrency for more details.	_etag
headers	A set of default headers to include with each request. You can use this API property directly, and there are helper functions too. See Request Headers for more details.	(details below)
error_handling	Determines when exceptions are thrown/raised. There are two properties: raise_for_network_errors raise_for_status_codes	(details below)

Default Headers

These are the headers that by default are sent with every request:

Content-type: application/json
Accept: application/hal+json, application/json;q=0.9, */*;q=0.8
Authorization: Basic cm9vdDpwYXNzd29yZA==

The default Authorization: header is root:password base-64 encoded. This is to provide the default credentials hypermea services use when in under development.

See the Request Headers page for more details.

Default Error Handling

There are two settings for error handling. Here are their defaults:

from halchemy import Api

api = Api('http://example.org/api')
print(api.error_handling.raise_on_network_error)  # True
print(api.error_handling.raise_on_status_codes)     # None

const {Api} = require('halchemy')

const api = new Api('http://example.org/api')
console.log(api.errorHandling.raiseOnNetworkError)  // true
console.log(api.errorHandling.raiseOnStatusCodes)     // null

require "halchemy"

api = Halchemy::Api.new "http://example.org/api"
puts api.error_handling.raise_on_network_error  # true
puts api.error_handling.raise_on_status_codes   # nil

See the Handling Errors page for more details.