HTTP Services

From DreamFactory
Jump to: navigation, search
Line 1: Line 1:
 
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.
 
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===
+
==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  [https://df-wiki.dreamfactory.com/df-swagger-ui/dist/index.html#!/getSystemServiceType here] using the '''''api/v2/system/service_type/rws''''' endpoint.
 
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  [https://df-wiki.dreamfactory.com/df-swagger-ui/dist/index.html#!/getSystemServiceType here] using the '''''api/v2/system/service_type/rws''''' endpoint.
  
Line 56: Line 56:
  
 
===CURL Options===
 
===CURL Options===
"name": "options",
+
 
"label": "CURL Options",
+
* 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.
"description": "This contains 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.",
+
"type": "object",
+
"object": {
+
"key": {
+
"label": "Name",
+
"type": "string"
+
},
+
"value": {
+
"label": "Value",
+
"type": "string"
+
}
+
}
+
  
 
===Parameters===
 
===Parameters===
"name": "parameters",
+
 
"label": "Parameters",
+
* parameters - Array of Objects. Parameters. Supply additional URL parameters to pass to the remote service, or exclude ones passed from client.",
"description": "Supply additional parameters to pass to the remote service, or exclude parameters passed from client.",
+
 
"type": "array",
+
Each parameter object consists of the following pieces.
"required": false,
+
  * name - String. Parameter name.
"allow_null": true,
+
  * value - Mixed. Value of the parameter to send, overrides any value sent from client.
"items": [{
+
  * exclude - Boolean. Exclude this parameter from the client from being sent to the remote service.
"name": "name",
+
  * cache_key- Boolean. Include this parameter and value in the cache key.
"label": "Name",
+
  * action - Integer. HTTP verb (aka action) mask for which verbs should this parameter be applied to. Defaults to 0.
"description": null,
+
"type": "string"
+
}, {
+
"name": "value",
+
"label": "Value",
+
"description": null,
+
"type": "text",
+
}, {
+
"alias": null,
+
"name": "exclude",
+
"label": "Exclude",
+
"description": null,
+
"type": "boolean",
+
"default": true
+
}, {
+
"name": "outbound",
+
"label": "Outbound",
+
"description": null,
+
"type": "boolean",
+
"default": true,
+
}, {
+
"name": "cache_key",
+
"label": "Cache Key",
+
"description": null,
+
"type": "boolean",
+
"default": true,
+
}, {
+
"name": "action",
+
"label": "Verbs",
+
"description": "Which REST verbs should this parameter be applied to.",
+
"type": "verb_mask",
+
"default": 0,
+
}]
+
  
 
===Headers===
 
===Headers===
"name": "headers",
+
 
"label": "Headers",
+
* headers - Array of Objects. Headers. Supply additional headers to pass to the remote service.
"description": "Supply additional headers to pass to the remote service.",
+
  * name - String.
"type": "array",
+
  * value - Mixed.
"required": false,
+
  * pass_from_client - Boolean. Pass From Client
"allow_null": true,
+
  * action - Integer. Verb Mask of which REST verbs should this header be applied to outgoing requests.
"items": [{
+
"alias": null,
+
"name": "name",
+
"label": "Name",
+
"description": null,
+
"type": "string",
+
"length": null,
+
"precision": null,
+
"scale": null,
+
"default": null,
+
"required": true,
+
"allow_null": false,
+
"fixed_length": false,
+
"supports_multibyte": false,
+
"is_primary_key": false,
+
"is_unique": false,
+
"is_foreign_key": false,
+
"is_virtual_foreign_key": false,
+
"is_foreign_ref_service": false,
+
"ref_service": null,
+
"ref_service_id": null,
+
"ref_table": null,
+
"ref_fields": null,
+
"ref_on_update": null,
+
"ref_on_delete": null,
+
"picklist": null,
+
"validation": null,
+
"db_function": null
+
}, {
+
"alias": null,
+
"name": "value",
+
"label": "Value",
+
"description": null,
+
"type": "text",
+
"length": null,
+
"precision": null,
+
"scale": null,
+
"default": null,
+
"required": false,
+
"allow_null": true,
+
"fixed_length": false,
+
"supports_multibyte": false,
+
"is_primary_key": false,
+
"is_unique": false,
+
"is_foreign_key": false,
+
"is_virtual_foreign_key": false,
+
"is_foreign_ref_service": false,
+
"ref_service": null,
+
"ref_service_id": null,
+
"ref_table": null,
+
"ref_fields": null,
+
"ref_on_update": null,
+
"ref_on_delete": null,
+
"picklist": null,
+
"validation": null,
+
"db_function": null
+
}, {
+
"alias": null,
+
"name": "pass_from_client",
+
"label": "Pass From Client",
+
"description": null,
+
"type": "boolean",
+
"length": 1,
+
"precision": null,
+
"scale": null,
+
"default": true,
+
"required": false,
+
"allow_null": false,
+
"fixed_length": false,
+
"supports_multibyte": false,
+
"is_primary_key": false,
+
"is_unique": false,
+
"is_foreign_key": false,
+
"is_virtual_foreign_key": false,
+
"is_foreign_ref_service": false,
+
"ref_service": null,
+
"ref_service_id": null,
+
"ref_table": null,
+
"ref_fields": null,
+
"ref_on_update": null,
+
"ref_on_delete": null,
+
"picklist": null,
+
"validation": null,
+
"db_function": null
+
}, {
+
"alias": null,
+
"name": "action",
+
"label": "Verbs",
+
"description": "Which REST verbs should this header be applied to outgoing requests.",
+
"type": "verb_mask",
+
"length": null,
+
"precision": null,
+
"scale": null,
+
"default": 0,
+
"required": false,
+
"allow_null": false,
+
"fixed_length": false,
+
"supports_multibyte": false,
+
"is_primary_key": false,
+
"is_unique": false,
+
"is_foreign_key": false,
+
"is_virtual_foreign_key": false,
+
"is_foreign_ref_service": false,
+
"ref_service": null,
+
"ref_service_id": null,
+
"ref_table": null,
+
"ref_fields": null,
+
"ref_on_update": null,
+
"ref_on_delete": null,
+
"picklist": null,
+
"validation": null,
+
"db_function": null
+
}]
+
  
 
===Caching===
 
===Caching===

Revision as of 13:31, 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 sections describe the configuration pieces of this service type.

Base URL

  • base_url - Text. Base URL (required if not defined in Service Definition). This is the root for the external call, additional resource path and parameters from client, along with provisioned parameters and headers, will be added.

CURL Options

  • 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

  • parameters - Array of Objects. 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

  • headers - Array of Objects. Headers. Supply additional headers to pass to the remote service.
 * name - String.
 * value - Mixed. 
 * pass_from_client - Boolean. Pass From Client
 * action - Integer. Verb Mask of which REST verbs should this header be applied to outgoing requests.

Caching

  • 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.