Request options

The HttpClient->request() method accepts it's own options
as well as options for the underlying RestMini Client.

Own options

• (bool) debug_dump: log request and response
• (bool|arr) cacheable: cache response/load response from cache
• (bool|arr) validate_response: validate the response body against a validation rule set
• (bool|arr) mock_response: don't send the request, return predefined mock response
• (int) retry_on_unavailable: millisecs; try again later upon
  503 Service Unavailable|host not found|connection failed
• (arr) require_response_headers: list of response header keys required
• (bool) err_on_endpoint_not_found: err on 404 + HTML response
• (bool) err_on_resource_not_found: err on 204 or 404 + JSON response
• (arr) log_warning_on_status: key is status code, value is true

Options processing

Apart from options passed directly to HttpClient->request()
there may also exist settings (see Config) for the:

• provider: the service host
• service: a group of endpoints
• endpoint: the actual endpoint
• method: literal HTTP method or an alias (like GET aliases index and retrieve)

During request preparations settings and options get merged, so that
– options override method settings, which override endpoint settings, which override... (you get it).
Sounds like a lot of work, but it isn't really.

# Show provider settings.
php cli.php config-get -a global http-provider.prvdr

# Show service settings.
php cli.php config-get -a global http-service.prvdr.example-service

# Show endpoint settings.
php cli.php config-get -a global http-endpoint.prvdr.example-service.ndpnt

# Show method settings.
php cli.php config-get -a global http-method.prvdr.example-service.ndpnt.GET

# Show cached validation rule set.
php cli.php cache-get http-response_validation-rule-set prvdr.example-service.ndpnt.GET

# Delete cached validation rule set.
php cli.php cache-delete http-response_validation-rule-set prvdr.example-service.ndpnt.GET

# Show cached mock response.
php cli.php cache-get http-response_mock prvdr.example-service.ndpnt.GET

# Delete cached mock response.
php cli.php cache-delete http-response_mock prvdr.example-service.ndpnt.GET

Producing a service response is not as hard as requesting a remote service,
so the service part of Http is not as rich as the client part.
It is assumed that one will simply echo something and send some headers – or use a service framework like Slim.

The HttpServiceSlim class suggest means of interacting with Slim, and Http includes a simple example. @todo
And Http also provides a few other service utilities.

Allowing Cross Origin requests

Preferably only at development site. Necessary when developing Angular-based frontend.

Place a .cross_origin_allow_sites text file in document root, containing list allowed sites, like:
http://localhost:4200,http://my-project.build.local.host:80

Http uses a number of custom response headers, to flag stuff to the client.
Some are issued by HttpClient upon every remote request (the original/final statuses).
Others are only issued if a service uses/sends one of the prefab HttpResponse extensions.

• ^(int)X-Http-Original-Status: status received from remote service (or interpretated ditto)
• ^(int)X-Http-Final-Status: final status to be sent to client
• X-Http-Response-Invalid: response validation failure; HttpResponseResponseInvalid
• X-Http-Mock-Response: HttpClient never called remote service; used prefab mock response
• X-Http-Request-Invalid: request header/argument validation failure; HttpResponseRequestInvalid
• X-Http-Request-Unacceptable: (some kind of) bad request; HttpResponseRequestUnacceptable
• X-Http-Request-Unauthenticated: authentication (login) failure; HttpResponseRequestUnauthenticated
• X-Http-Request-Unathorized: authorization (permission) failure; HttpResponseRequestUnauthorized