HTTP Services

From DreamFactory
Jump to: navigation, search
(Events)
(Service Definition)
Line 71: Line 71:
  
 
==Service Definition==
 
==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 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 Specification, just import that JSON or YAML file in as the service definition, otherwise write your own [http://editor.swagger.io/#/ here].
  
 
==Events==
 
==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 '''''<nowiki>http://example.com/api/v2/myservice/makes/count</nowiki>'''''.
 
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 '''''<nowiki>http://example.com/api/v2/myservice/makes/count</nowiki>'''''.

Revision as of 15:25, 27 July 2016

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. 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 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. 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 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 Specification, just import that JSON or YAML file in 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.