Web Services

Version 2013-03-01

Heirloom Computing Web Services provides a RESTful interface to everything you can do with the Web-based Portal. For more information, see the Heirloom Computing and Heirloom web portals.

Note:  Access your LaaS server (an Heirloom cloud instance you started) with its URL:

http://myco.instances.heirloomcomputing.com/rest/2013-03-01/index.html

Log into this page with your HCI registered user ID and password.  Once you see the then access the Web Services on your instances under your designated HC_DOMAIN assigned to you.  Each LaaS wil have a different set of customer, product. license, restriction records recorded under this domain.  Web services issued against this domain will use the subscription email and password you set up for them.

Operations:

• customer (test) -- Manage the definition of Application Development and Enterprise Legacy Platforms-as-a-Service
• index (test) -- Self-documentation module for Heirloom Computing Web Services
• license (test) -- Manage licenses of various products on a multitude of platforms granted to a specific subscription (customer)
• licensecheck (test) -- Validate whether a subscriber has access to a product. Checking includes whether the either the subscription, license type or license is enabled, whether a limit in the number of unique MAC addresses, gateway IPs or host machines from which the product is executing has been reached, and whether the license has expired.
• loglicense (test) -- Manage logging activities on licenses
• ping (test) -- Indicate the health of the REST Web Services
• product (test) -- Manage product definitions
• restriction (test) -- Manage restrictions associated with licenses

REST Operations and Format

All REST calls are issued over HTTPS to Heirloom Computing portals to encrypt the data, the request operation and the basic authentication header information exchanged between the REST client and the portal. The URI path begins with rest followed by the API version, of which latest always refers to the most current API version. The API operation that is to be carried out comes next on the URI path. If the operation acts on a specific object, rather than all of the objects, its ID follows on the URI path. Finally, the URI includes the API's optional and required parameters. For example,

GET https://elasticcobol.com/rest/2013-03-01/operation/objectid?required-parameters&optional-parameters

As with most RESTful Web services, many operations support one or more HTTP directives. Generally, URLs typed into a browser's address bar issue the GEToperation. Here are the most common HTTP directives.

Operation	Description
GET	Retrieve information about one or more objects
PUT	Create a new object
POST	Update an existing object
DELETE	Remove an existing object

Common Headers and Parameters

HTTP heaaders may be supplied with the request to modify the behavior or supply additional authentication information. Parameters common to all REST Web services are:

Parameter	Description	Required
timestamp	All requests must be timestamped within an hour of the request. Format for this parameter is in ISO Date Format,YYYY-MM-DDTHH:MM:SS	Yes
Authorization	The Authorization HTTP header is required on most API calls and serves to identify the individual carrying out the operation. The subscriber (customer) must have the authority (role) to carry out the operation of the Web service.	Yes
HC_SUBSCRIPTION_ID	This HTTP header is required only on the licensecheck operation and an alternative on other APIs to providing theAuthorization header for identification or the objectid or subid parameter to specify the subscription for which the operation is to be associated.	No
HC_EMAIL_ADDRESS	This HTTP header is required only on the licensecheck operation and an alternative on other APIs to providing theAuthorization header for identification or the objectid or subid parameter to specify the subscription for which the operation is to be associated.	No
HC_DOMAIN	The HC_DOMAIN indicate the HCI-approved private cloud domain to which the operations apply. Do not specify this header for the public Heirloom cloud environment.	No