HTTP Services

From DreamFactory
Jump to: navigation, search
(Created page with "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 a...")
 
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===
 +
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.
 +
 +
Below is the format of a typical HTTP Service configuration.
 +
<source lang="javascript">
 +
{
 +
"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
 +
}
 +
}
 +
</source>
 +
 +
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===
 +
"name": "options",
 +
"label": "CURL Options",
 +
"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===
 +
"name": "parameters",
 +
"label": "Parameters",
 +
"description": "Supply additional parameters to pass to the remote service, or exclude parameters passed from client.",
 +
"type": "array",
 +
"required": false,
 +
"allow_null": true,
 +
"items": [{
 +
"name": "name",
 +
"label": "Name",
 +
"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===
 +
"name": "headers",
 +
"label": "Headers",
 +
"description": "Supply additional headers to pass to the remote service.",
 +
"type": "array",
 +
"required": false,
 +
"allow_null": true,
 +
"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===
 +
 +
* 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.

Revision as of 20:48, 26 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

"name": "options", "label": "CURL Options", "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

"name": "parameters", "label": "Parameters", "description": "Supply additional parameters to pass to the remote service, or exclude parameters passed from client.", "type": "array", "required": false, "allow_null": true, "items": [{ "name": "name", "label": "Name", "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

"name": "headers", "label": "Headers", "description": "Supply additional headers to pass to the remote service.", "type": "array", "required": false, "allow_null": true, "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

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