Hostway API Documentation - User contributions [en]

Orders-orderId:GET

2013-08-21T16:11:09Z

Yulia.uzunova: /* Parameters */

= GET /orders/''{orderId}'' =
Returns the content of an order specified by the URI.
__TOC__
== Request ==
<code>GET /orders/''{orderId}''</code>

==== Parameters ====
{{UriParameter-OrderId}}

=== URI Parameters ===
None.

=== Request Headers ===
{{Cookie-OwnerId}}

; Authorization
: Optional. Specify the '''Authorization''' header when requesting details for an order that was already submitted. Follow the instructions for API [[Authentication]].

== Response ==

=== Status Code ===
;200 OK
: Success.

;401 Unauthorized
: The '''OwnerId''' cookie or the '''Authorization''' header are not specified or do not permit access to the specified order.

;404 Not Found
: The specified order does not exist.

=== Response Body ===
The response body may contain additional information beyond what is specified in the documentation. Such information should be ignored or treated as volatile, since it may change in the future.

<nowiki>
{
"order": {
"Status": "{orderStatus}",
"Account": "{accountUrl}"
},
"links": {
"self": {"href": "</nowiki>{{APIBaseURL}}<nowiki>/orders/{orderId}/", "rel": "self"}
}
}
</nowiki>

==== Parameters ====
; orderStatus - ''string''
: The status of the order.

; accountUrl - ''string (optional)''
: [[Hypermedia]] for the account of this order. Link to the account.

; links - ''list''
: [[Hypermedia]] for this resource. Link to the order.

== Example ==

=== Request ===
<nowiki>
GET /orders/0000013ca61880fbfc068b33000a02c9d8ef861c
Cookie: OwnerId=948ce0d4-7cf0-43b6-88a5-2b3f1331b689; Path=/
</nowiki>

=== Response ===
<nowiki>
200 OK
Content-Type: application/json; charset=UTF-8

{
"order": {
"Status": "new",
"Account": "http://accounts/acc20130821"
},
"links": {
"self": {"href": "</nowiki>{{APIBaseURL}}<nowiki>/orders/0000013ca61880fbfc068b33000a02c9d8ef861c/", "rel": "self"}
}
}
</nowiki>

== OPTIONS /orders/''{order_id}'' ==
In addition to the GET method the API supports the OPTIONS method for direct browser access to the API. The format of the request is:

<code>OPTIONS /orders/''{order_id}''</code>

==== Parameters ====
; order_id - ''string''
: The unique order Id. The full URI of each order is returned by the [[Orders:POST|POST /orders]] call.

=== Request Headers ===
; Cookie
: A cookie named '''OwnerId''' to identify the client (for most browser clients, the browser will do this automatically, depending on the browser configuration). The value of the cookie would come from the response to the create order request in the '''Set-Cookie''' response header.

=== Response Status Code ===
;200 OK
: Success.

;404 Not Found
: The specified order does not exist.

=== Response Headers ===
;Access-Control-Allow-Methods
: A comma-separated list of request methods supported on this URI.

;Access-Control-Allow-Origin
: All origins are allowed. This header has value '''*'''.

== See also ==
* [[Orders|Orders API]]
* [[Common Features]]

{{disqus}}
[[Category:Hostway API]]
[[Category:Ordering API]]

ProductSpecifications-productSpecificationId-offerings-offeringId-prices:GET

2013-07-30T15:27:52Z

Yulia.uzunova: /* URI Parameters */

= GET /productSpecifications/''{productSpecificationId}''/offerings/''{offeringId}''/prices =
Retrieves prices for a particular product specification offering.
__TOC__

== Request ==
<code>GET /productSpecifications/''{productSpecificationId}''/offerings/''{offeringId}''/prices</code>

=== URI Parameters ===
;filterType
: Indicates that the result should be filtered by price type.
: The legal values for this parameter are 'fee', 'discount' and 'usage_fee'
: '''''fee''''' - all product specification and its service specifications prices (e.g. setup fee, recurring fee, etc.)
: '''''discount''''' - all product specification and its service specifications discounts
: '''''usage_fee''''' - all product specification and its service specifications usage prices
: This parameter CANNOT be used with values containing any wildcards (*)

: This parameter is optional

;filterRecurrences
: Indicates that the result should be filtered by the number of recurrences
: This parameter is optional.
: The values for this parameter can be specified using a wildcard(*).

;filterRelatedServiceSpecification
: Indicates that the result should be filtered by linked service specification URI.
: A value of '' indicates that only results with relatedServiceSpecification='' should be returned.
: This parameter is optional
: This parameter CANNOT be used with values containing any wildcards (*)

;filterName
: Indicates that the result should be filtered by name
: This parameter is optional
: This parameter CANNOT be used with values containing any wildcards (*)

;sortField
: Indicates which field should be used for sorting.
: Legal values are 'name', 'type', 'recurrences' and 'relatedServiceSpecification'.
: This parameter is optional

;sortOrder
: Indicates the order in which the result should be sorted.
: Legal values are 'asc' and 'desc'
: This parameter is optional. If 'sortField' was specified and 'sortOrder' was omitted, then the result will be sorted in ascending order.

;pageSize
: Indicates the number of prices to be included on each page of the result (if pagination is desired)
: This parameter is optional. If 'page' is specified and 'pageSize' is omitted, then the result will show 100 prices per page.

;page
: Indicates the 1-based index of the page to view.
: The value must be an integer between 1 and the maximum number of pages (returned in the 'last' element of the 'links' attribute of the result)
: This parameter is optional, but if 'pageSize' was specified, then 'page' is also required.

== Response ==
Returns a list of prices for a particular product specification offering Id.

=== Status Code ===
;200 OK
: Success

;400 Bad Request
: Returned if incorrect parameters are specified for filtering, sorting or pagination. The response body will contain details about the nature of the error.

;404 Not Found
: Returned if the product specification Id or the offering Id could not be found.

;502 Bad Gateway
: Returned there is any internal API error.

=== Response Body ===
<nowiki>
{
"list": [
{
"type": "fee"
"name": "recurring",
"amount": 1125.0,
"billingPeriod": 3,
"recurrences": -1,
"relatedServiceSpecification": "</nowiki>{{APIBaseURL}}<nowiki>/serviceSpecifications/{serviceSpecificationId}",
},
{
"type" : "usage_fee",
"name" : "mfg_mailbox_standard",
"billingPeriod" : 1,
"relatedServiceSpecification" : "</nowiki>{{APIBaseURL}}<nowiki>/serviceSpecifications/{serviceSpecificationId}",
"unit" : "mfg_mailbox_standard",
"rates" : [
{
"start" : 1,
"end" : 3,
"amountPerUnit" : 0.0
},
{
"start" : 3,
"end" : -1,
"amountPerUnit" : 1.0
}
]
}
],
"links": [
{
"rel": "self",
"href": "</nowiki>{{APIBaseURL}}<nowiki>/productSpecifications/{productSpecificationId}/offerings/{offeringId}/prices?pageSize={pageSize}&page=3"
},
{
"rel": "first",
"href": "</nowiki>{{APIBaseURL}}<nowiki>/productSpecifications/{productSpecificationId}/offerings/{offeringId}/prices?pageSize={pageSize}&page=1"
},
{
"rel": "previous",
"href": "</nowiki>{{APIBaseURL}}<nowiki>/productSpecifications/{productSpecificationId}/offerings/{offeringId}/prices?pageSize={pageSize}&page=2"
},
{
"rel": "next",
"href": "</nowiki>{{APIBaseURL}}<nowiki>/productSpecifications/{productSpecificationId}/offerings/{offeringId}/prices?pageSize={pageSize}&page=4"
},
{
"rel": "last",
"href": "</nowiki>{{APIBaseURL}}<nowiki>/productSpecifications/{productSpecificationId}/offerings/{offeringId}/prices?pageSize={pageSize}&page=12"
},
]
}
</nowiki>

==== Parameters ====
; list - ''list''
: List of product offering price details. Each element of the list has the following attributes:

:; type - ''string''
:: This can be either 'fee', 'discount' or 'usage_fee'. A fee represents a fee that will be charged. A discount represents a downward adjustment of the amount of a fee.
An usage fee represents a fee that will be charged based on usage rate.

:; name - ''string''
:: A name for the price. This is NOT guaranteed to be unique.

:; billingPeriod - ''integer''
:: The billing frequency in months.

:; recurrences - ''integer''
:: The number of time this price will recur. A value of -1 means that the price will recur throughout the entire lifetime of the provisioned product.
:: This parameter is available for '''''fee''''' and '''''discount''''' types only

:; relatedServiceSpecification - ''string''
:: The URI of the service specification (associated with the product) to which this price is linked. If this is an empty string, then the price is linked to the product itself.

:; unit - ''string''
:: unit based on which a service is charged for.
:: This parameter is available for '''''usage_fee''''' type only

:; rates - ''dictionary''
:: tiers of usage on which a service is charged for. Each tier has:
::; start - ''integer''
::: number of unit for which a service begins to be charged with the '''current''' tier's price. The start of a tier is '''inclusive for the current tier'''.

::; end - ''integer''
::: number of unit for which a service begins to be charged with the '''next''' tier's price. The end of a tier is '''exclusive for the current tier'''. If the '''end''' parameter is '''-1''', then we have no limit for the tier.

::; amountPerUnit - ''float''
::: Price per an usage unit to be charged.

== Examples ==

=== Get usage tiers for a given service specification of a product ===
'''Request'''

<nowiki>
GET http://127.0.0.1:6543/productSpecifications/core.plan.linux.webstart/offerings/USD-1/prices?filterRelatedservicespecification=/serviceSpecifications/core.email.openxchange.xmail&filterType=usage_fee
</nowiki>

'''Response'''

'''HTTP/1.0 200 OK'''
<nowiki>
{
"list" : [ {
"name" : "mfg_mailbox_standard",
"billingPeriod" : 1,
"rates" : [ {
"start" : 1,
"end" : 3,
"amountPerUnit" : 0.0
}, {
"start" : 3,
"end" : -1,
"amountPerUnit" : 1.0
} ],
"relatedServiceSpecification" : "http://127.0.0.1:6543/serviceSpecifications/core.email.openxchange.xmail",
"type" : "usage_fee",
"unit" : "mfg_mailbox_standard"
}, {
"name" : "mfg_mailbox_activesync",
"billingPeriod" : 1,
"rates" : [ {
"start" : 1,
"end" : -1,
"amountPerUnit" : 2.0
} ],
"relatedServiceSpecification" : "http://127.0.0.1:6543/serviceSpecifications/core.email.openxchange.xmail",
"type" : "usage_fee",
"unit" : "mfg_mailbox_activesync"
}, {
"name" : "mfg_mailbox_premium",
"billingPeriod" : 1,
"rates" : [ {
"start" : 1,
"end" : -1,
"amountPerUnit" : 3.0
} ],
"relatedServiceSpecification" : "http://127.0.0.1:6543/serviceSpecifications/core.email.openxchange.xmail",
"type" : "usage_fee",
"unit" : "mfg_mailbox_premium"
} ],
"links" : [ {
"href" : "http://127.0.0.1:6543/productspecifications/core.plan.linux.webstart/offerings/USD-1/prices?filterRelatedservicespecification=/serviceSpecifications/core.email.openxchange.xmail&filterType=usage_fee",
"rel" : "self"
} ]
}
</nowiki>

=== Get usage tiers for a given service specification of a product filtered by an usage rate's name ===
'''Request'''

<nowiki>
http://127.0.0.1:6543/productSpecifications/core.plan.linux.webstart/offerings/USD-1/prices?filterRelatedservicespecification=/serviceSpecifications/core.email.openxchange.xmail&filterType=usage_fee&filterName=mfg_mailbox_standard
</nowiki>

'''Response'''

'''HTTP/1.0 200 OK'''
<nowiki>
{
"list" : [ {
"name" : "mfg_mailbox_standard",
"billingPeriod" : 1,
"rates" : [ {
"start" : 1,
"end" : 3,
"amountPerUnit" : 0.0
}, {
"start" : 3,
"end" : -1,
"amountPerUnit" : 1.0
} ],
"relatedServiceSpecification" : "http://127.0.0.1:6543/serviceSpecifications/core.email.openxchange.xmail",
"type" : "usage_fee",
"unit" : "mfg_mailbox_standard"
} ],
"links" : [ {
"href" : "http://127.0.0.1:6543/productspecifications/core.plan.linux.webstart/offerings/USD-1/prices?filterRelatedservicespecification=/serviceSpecifications/core.email.openxchange.xmail&filterType=usage_fee&filterName=mfg_mailbox_standard",
"rel" : "self"
} ]
}
</nowiki>

== See also ==
* [[Products|Product Catalog API]]
* [[Common Features]]

{{disqus}}
[[Category:Hostway API]]
[[Category:Product Catalog API]]

GET Exchange Global Contacts list

2013-07-30T14:50:04Z

Yulia.uzunova: /* Parameters */

Retrieve an Exchange Global contacts list by domain name

'''GET''' <code>/accounts/''account-number''/exchange/''domain-name''/globalContacts</code>

'''GET''' <code>/accounts/''account-number''/exchange/''domain-name''/globalContacts?page=''page-num''&pageSize=''page-size''&sortField=''sort-field''&sortOrder=''sort-order''&''filter-field''=''filter-value''</code>

== Parameters ==
; account-number - ''string''
: The account-number that the Exchange resource belongs to

; domain-name - ''string''
: The domain-name that is associated with the Exchange resource

; page-num- ''int''
: ''(OPTIONAL)''
: Request a specific page of data. If not set defaults to 1

; page-size - ''int''
: ''(OPTIONAL)''
: Size used to paginate the request. If not set defaults to 100

; sort-field - ''string''
: ''(OPTIONAL)''
: Specifies a field upon which to sort the data. If not set no sorting is preformed. Allowed values are specified by an OPTIONS request

; sort-order - ''string''
: ''(OPTIONAL)''
: Specifies the order in which the data is sorted. If not set no sorting is preformed if ''sort-field'' is not set or defaults to asc otherwise. Allowed values are specified by an OPTIONS request

; filter-field - ''string''
: ''(OPTIONAL)''
: Specifies a field upon which the data is filtered. If multiple ''filter-field'' are set all of them have to be true to pass the filter. If none are set no filtering is performed. Allowed values are specified by an OPTIONS request. Example: if we want to filter by field 'status' then the paramenter should look like 'filterStatus=value'. That way one can filter by more then one field. The filtering values can be also specified using wildcards(*).

; filter-value - ''string''
: ''(OPTIONAL)''
: A value with which the ''filter-field'' is filtered. Values are either an exact match or a partial match using a wildcards(*). Additional restrictions may be specified by an OPTIONS request

== Response Body ==
<nowiki>
{
"list" :
[
{
"details" : "http://{server_name}/accounts/{account_number}/exchange/{domain_name}/globalContacts/{global_contact_id}/",
"target" : "test@test.com",
"name" : "display name of the contact"
},
{
"details" : "http://{server_name}/accounts/{account-number}/exchange/{domain-name}/globalContacts/{global_contact_id}/",
"target" : "test1@test1.com",
"name" : "display name of the contact"
}
]
"links":
[
{
"href" : "http://{server_name}/accounts/{account-number}/exchange/{domain-name}/globalContacts?page=2&pageSize=2",
"rel" : "self"
},
{
"href" : "http://{server_name}/accounts/{account-number}/exchange/{domain-name}/globalContacts?page=1&pageSize=2",
"rel" : "first"
},
{
"href" : "http://{server_name}/accounts/{account-number}/exchange/{domain-name}/globalContacts?page=1&pageSize=2",
"rel" : "previous"
},
{
"href" : "http://{server_name}/accounts/{account-number}/exchange/{domain-name}/globalContacts?page=1&pageSize=3",
"rel" : "next"
},
{
"href" : "http://{server_name}/accounts/{account-number}/exchange/{domain-name}/globalContacts?page=1&pageSize=3",
"rel" : "last"
}
]
}
</nowiki>

; list - ''list''
: List of the global contacts for the selected domain. Each element of the list has the following attributes:

:; name - ''string''
:: The name of the contact

:; target - ''string''
:: Email of the contact

:; details - ''string''
:: Hyperlink to the contact

; links - ''list''
: [[Hypermedia]] for this resource. Link to self will preserve filtering, sorting and pagination set by the request. Links to the first, last, previous and next pages will also be included if applicable

=== Expected Response Codes ===
;200
: Success

;400
: Bad request

;404
: Non-existent resource

;405
: Unsupported method

;502
: Internal server error

== Examples ==
'''GET''' <code>''{server_name}''/accounts/''account300021''/exchange/''ng-test-hwus-120120b.com''/globalContacts</code>

''- Request Headers:''
Content-Type:application/json
Charset=UTF-8
Authorization:Base64-encoded username & password string

''- Response:''
''OK (200)'':
<nowiki>
[
{
"details": "http://{server_name}/accounts/account300021/exchange/ng-test-hwus-120120b.com/globalContacts/00000136a0dc303df040b174000ae6fa2cb8a7d8/",
"target": "name@domain.com",
"name": "My old descriptive name"},
{
"details": "http://{server_name}/accounts/account300021/exchange/ng-test-hwus-120120b.com/globalContacts/0000013659099524e2c12a99000a91275a05bc87/",
"target": "target3@domain.com",
"name": "new name"
}
]
</nowiki>

[[Category:Hostway API]]
[[Category:Exchange API]]

GET Exchange Email Aliases list

2013-07-30T14:46:42Z

Yulia.uzunova: /* Parameters */

Retrieve an Exchange Email Aliases list by domain name

'''GET''' <code>/accounts/''account-number''/exchange/''domain-name''/emailaliases</code>

'''GET''' <code>/accounts/''account-number''/exchange/''domain-name''/emailaliases?page=''page-num''&pageSize=''page-size''&sortField=''sort-field''&sortOrder=''sort-order''&''filter-field''=''filter-value''</code>

== Parameters ==
; account-number - ''string''
: The account-number that the Exchange resource belongs to

; domain-name - ''string''
: The domain-name that is associated with the Exchange resource

; page-num- ''int''
: ''(OPTIONAL)''
: Request a specific page of data. If not set defaults to 1

; page-size - ''int''
: ''(OPTIONAL)''
: Size used to paginate the request. If not set defaults to 100

; sort-field - ''string''
: ''(OPTIONAL)''
: Specifies a field upon which to sort the data. If not set no sorting is preformed. Allowed values are specified by an OPTIONS request

; sort-order - ''string''
: ''(OPTIONAL)''
: Specifies the order in which the data is sorted. If not set no sorting is preformed if ''sort-field'' is not set or defaults to asc otherwise. Allowed values are specified by an OPTIONS request

; filter-field - ''string''
: ''(OPTIONAL)''
: Specifies a field upon which the data is filtered. If multiple ''filter-field'' are set all of them have to be true to pass the filter. If none are set no filtering is performed. Allowed values are specified by an OPTIONS request. Example: if we want to filter by field 'status' then the paramenter should look like 'filterStatus=value'. That way one can filter by more then one field.The values can be also specified using wildcards(*).

; filter-value - ''string''
: ''(OPTIONAL)''
: A value with which the ''filter-field'' is filtered. Values are either an exact match or partial match using a wildcard(*). Additional restrictions may be specified by an OPTIONS request

== Response ==
Returns a dictionary with shorten information about email aliases of the Exchange product associated with the given domain name

=== Response Body ===
<nowiki>
{
"list" : [ {
"emailAlias" : "email_alias_1@example.com",
"details" : "http://{server-name}/accounts/{account-number}/exchange/{domain-name}/emailaliases/email_alias_1"
}, {
"emailAlias" : "email_alias_2@example.com",
"details" : "http://{server-name}/accounts/{account-number}/exchange/{domain-name}/emailaliases/email_alias_2"
}],
"links" : [ {
"href" : "http://{server-name}/accounts/{account-number}/exchange/{domain-name}/emailaliases/",
"rel" : "self"
} ]
}
</nowiki>

; list - ''list''
: List of the email aliases for the selected domain. Each element of the list has the following attributes:

:; emailAlias - ''string''
:: The email alias address

:; details - ''string''
:: Hyperlink to the email alias' details

; links - ''list''
: [[Hypermedia]] for this resource. Link to self will preserve filtering, sorting and pagination set by the request. Links to the first, last, previous and next pages will also be included if applicable

''The details hyperlink and hypermedia's parameters are as following:''
; {server-name} - ''string''
: The name of the server from which the resources are requested

; {account-number} - ''string''
: The account-number that the Exchange resource belongs to

; {domain-name} - ''string''
: The domain-name that is associated with the Exchange resource

=== Expected Response Codes ===
;200
: Success

;400
: Bad request
: This is usually a sign that the client attempted to use filtering/sorting criteria that are invalid for this resource

;404
: Non-existent resource
: Returned if no Exchange service could be found for the given domain name.

;405
: Unsupported method

;500
: Internal server error

;502
: Bad gateway
: There was a failure in an upstream service that caused a failure in the API.

[[Category:Hostway API]]
[[Category:Exchange API]]