Skip to end of metadata
Go to start of metadata

Overview

The service gateway's primary purpose is to accept incoming HTTP requests and forward them as AMQP messages and waiting for their response, while applying system boundary security, such as actor identification.

The Service Gateway has the following capabilities:

  • Bridge between external request encoding (e.g. JSON, REST, SOAP) and internal Common Message Format
  • Bridge between external transport protocol (e.g. HTTP/sockets) and internal transport protocol (AMQP)
  • Enforce policy at the boundary of the domain of authority

See Also:

Service Gateway

Characteristics

  • Runs as service in a R2 Python CC (pyon)
  • Provides a web server (port 5000) via flask - the hostname and port are configurable in pyon.yml
  • Translates JSON -> ION common message format (AMQP) for request and ION message -> JSON for response
  • Evaluates user session cookie, associates with web session and security context
  • Associates with permanent user presence (user agent)
  • Can be run as HA service on EPU (more than one instance)
  • Can be web loadbalanced

The following diagram illustrates the use of the Service Gateway by the front-end UI server:

See Also:

Supported HTTP Operations:

Notes on Authentication:

The requester parameter should be used to specify the user id which will be used as the ion-actor-id header in service request messages. The expiry parameter should be used to specify the time in milliseconds from epoch time ( as a string ) for when the requester's certification is valid. As a domain of authority boundary, the Service Gateway will check the validity of the user id and verify that the expiry value is not greater than the current time; else the request will be denied.

If a requester parameter is not supplied as part of the JSON request or on the URL as part of the query string, or if the user id passed in is not found to be a valid ION registered user, then the request will be handled as if it was an anonymous user.  If system policies are loaded and operational, then all service operations are not available to anonymous users so a legitimate user_id must be supplied as a requester. The user associated with the user_id must then also have the appropriate role associated with it for certain system operations.

Operations which cannot be completed because of policy checks will be returned with an appropriate Denied message.

The Service Gateway can also be configured to operate within a chain of trust  by only accepting requests from a specified list of trusted IP addresses. Trusted IP addresses can be added to the  pyon.yml Service Gateway configuration block.

Service Gateway Request

This is a service operation for handling generic service operation calls with arguments passed as query string parameters or within a JSON structure. Any service registered and running in a container can

be called using this HTTP interface. ( Note: examples below are using the curl command syntax but similar calls would need to be done via a browser AJAX request )

Refer to the actual service documentation for the description of the operation and expected return values.

The URL format for the request is:

such as:

where the JSON data below would be POSTed.

The format of the JSON string is as follows and POSTed as the value for a form variable named "payload", like this:

Where each parameter in the params block correlates to a service operation argument and its value to be passed in.

To specify ION objects, a dictionary of fields and values needs to be passed in and the "type_" field must be included with the name of the object (Resource Type) being passed in.

Resource Agent Gateway Request

This is a operation for handling resource agent operation calls with arguments passed in an JSON structure. Any service registered and running in a container can

be called using this HTTP interface. ( Note: examples below are using the wget command syntax but similar calls would need to be done via a browser AJAX request )

Refer to the actual service documentation for the description of the operation and expected return values.

The URL format for the request is:

such as:

where the JSON data below would be POSTed.

The format of an Agent command execute_agent call using a JSON string is as follows and POSTed as the value for a form variable named "payload", like this:

Where each parameter in the params block correlates to a service operation argument and its value to be passed in. For objects, a two element list is used for the value of the object where the first element in the list is the object type and the second element in the list is a dictionary of values to be passed as fields values of the object.

Example 1:  to call the find_resources operation in the Resource Registry service, make the following HTTP GET request:

Or call the similar URL as an HTTP POST with the parameters passed in posted JSON object; this example post of json data using wget:

Assuming the example bank service has been run, the JSON response would look similar to this:

Example 2: JSON HTTP post for calling the create operation in the resource registry service with paramaters for a BankAccount object

The JSON response would look similar to the following:

Example 3: JSON HTTP post for calling a higher level service; to call the create_exchange_space operation in the exchange management service with parameters for an ExchangeSpace object and an Org ID.

The JSON response would look similar to the following:

Example 4: JSON HTTP post for calling an agent and executing a command:

RESTful Services

List Resource Types

This restful method returns the list of registered resource objects sorted alphabetically. Optional query string parameter will filter by extended type i.e. type=InformationResource. All registered objects will be returned if not filtered

Find Resources By Type

A restful operation to return a list of resources of a specific resource type, for example:

Get Resource

A restful operation to call the resource registry with an id of a resource object passed in as part of the URL

Get Resource Schema

A restful operation to return the JOSN schema of the resource object passed in as part of the URL

Get Attachment

A restful operation to return the binary content of a Resource Registry attachment. The mime-type will be set to the value stored with the Attachment objects meta data

List Org Roles

A restful operation to return a list of Org roles for a specified actor

Get Visualization

A restful operation to return the visualization image associated with a data product

This route needs to be refactored!

Get Version Information

A restful operation to return a list versions associated with the ION system.

Http Operation Response

The Service Gateway has a standard format for responding to a request. If the request is well formed and handled by the gevent web server, then it will always have an HTTP response code of 200; otherwise standard web server response codes will be returned by the internal web server.

Successful Gateway Response

All responses will have a standard JSON response format and will include a request specific response as well as follows:

data:

Gateway Error Response

All error responses have a standard JSON response format as follows:

Labels

servicespec servicespec Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.