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, and therefore utilize role-service-access, lookup keys, 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 in 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 elements 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 the client, along with provisioned parameters and headers.
• options - Object/Associative Array. Optional. cURL options containing name-value pairs of any additional cURL settings to use when making remote web service requests, described as CUROPT_XXX at https://php.net/manual/en/function.curl-setopt.php. Notable options include CURLOPT_USERPWD for HTTP basic authentication, CURLOPT_PROXY and CURLOPT_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 the client. Each parameter object consists of the following pieces:
  • name - String. Required. Parameter name.
  • value - Mixed. Optional. Value of the parameter to send, overrides any value sent from client.
  • exclude - Boolean. Defaults to false. Exclude this parameter from the client from being sent to the remote service.
  • cache_key - Boolean. Defaults to false. Include this parameter and value in the cache key.
  • action - Integer. Defaults to 0 (none). HTTP verb (aka action) mask for which verbs should this parameter be applied to.

• 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). HTTP verb (aka action) mask for which verbs should this header be applied to outgoing requests.

• cache_enabled - Boolean. Defaults to false. 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. Required if enabled. 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.

Service Definition

Providing a service definition for HTTP services is optional, but very beneficial. The service will operate as normal without a definition, but the following are benefits from providing one:

• Base URL can be determined directly from the definition. The base_url is set to the OpenAPI (Swagger 2.0) Specification schemas (http/https) + host value + basePath value.
• Role service access can only be used for controlling access to individual resources/paths on the service if the paths are defined in the definition. Service level access can be controlled without a definition.
• Scriptable events can only be generated on the service if the paths are defined in the definition.

If the remote service already has a well defined OpenAPI (Swagger 2.0) Specification, just import that JSON or YAML file as the service definition, otherwise write your own here.

Events

HTTP Services, by default, fire no events unless there are paths defined in the Open-API/Swagger Specification. In that case, events are generated based on calls matching paths defined. The event myservice.makes.count.get would be generated for a GET call to http://example.com/api/v2/myservice/makes/count.