HTTP Services

HTTP Services, formerly known as Remote Web Services, allow DreamFactory to extend its API by adding a generic interface to connect to remote web services. HTTP services are also treated like native services in regards to role-service-access, lookup usage, live API documentation, and caching. With DreamFactory managing the service, many of the complex details of the remote web service can be hidden from the client. Service credentials, URL parameters, and headers can all be configured once and stored on the instance. This provides the client a simple, secure, and consistent way to access any remote web service via the DreamFactory REST API.

Configuration

HTTP Services are managed via the api/v2/system/service API endpoint under the system service and have the service type of rws. The service type for information can be retrieved from here using the api/v2/system/service_type/rws endpoint.

Below is the format of a typical HTTP Service configuration.

{
	"id": 1,
	"name": "example",
	"label": "Example Web Service",
	"description": "Some details about the service.",
	"is_active": true,
	"type": "rws",
	"mutable": true,
	"deletable": true,
	"created_date": "2016-07-20 14:30:39",
	"last_modified_date": "2016-07-20 14:30:39",
	"created_by_id": "1",
	"last_modified_by_id": null,
	"config": {
		"service_id": 1,
		"base_url": "http://example.com/api/",
		"options": {
			"some_option": "some_value"
		},
		"parameters": [{
			"id": 1,
			"service_id": 1,
			"name": "api_key",
			"value": "example_key_value",
			"exclude": false,
			"outbound": true,
			"cache_key": false,
			"action": 31
		}],
		"headers": [{
			"id": 2,
			"service_id": 1,
			"name": "example",
			"value": "test",
			"pass_from_client": false,
			"action": 1
		}],
		"cache_enabled": false,
		"cache_ttl": 0
	}
}

The following describes the configuration pieces of this service type.

• base_url - Text. Required if not defined in Service Definition. The base URL is the root for the external call, additional resource path and parameters from client, along with provisioned parameters and headers, will be added to complete the call to the remote service.

• options - Object/Associative Array. CURL Options. This contains name-value pairs of any additional CURL settings to use when making remote web service requests, described as CUROPT_XXX at http://php.net/manual/en/function.curl-setopt.php. Notable options include PROXY and PROXYUSERPWD for getting calls through proxies.

• parameters - Array of Objects. Optional. Parameters supply additional URL parameters to pass to the remote service, or exclude ones passed from client. Each parameter object consists of the following pieces.
  • name - String. Parameter name.
  • value - Mixed. Value of the parameter to send, overrides any value sent from client.
  • exclude - Boolean. Exclude this parameter from the client from being sent to the remote service.
  • cache_key- Boolean. Include this parameter and value in the cache key.
  • action - Integer. HTTP verb (aka action) mask for which verbs should this parameter be applied to. Defaults to 0.

• headers - Array of Objects. Optional. Headers supply additional headers to pass to the remote service. Each header object consists of the following pieces.
  • name - String. Required. Header name.
  • value - Mixed. Optional. Value of the header to send, unless pass_from_client is set to true, then this value is only sent when none provided by the client.
  • pass_from_client - Boolean. Defaults to false. Pass any client-sent value through to the remote service.
  • action - Integer. Defaults to 0 (none). Verb Mask of which REST verbs should this header be applied to outgoing requests.

• cache_enabled - Boolean. Enable data retrieval caching. Set to true to enable caching of GET requests particularly for this service. Only GET requests without payload are cached.
• cache_ttl - Integer. Cache Time To Live (minutes). The amount of time each cached response is allowed to last. Once expired, a new request to the service is made.