Orders-orderId-account-products-productId-services:POST

POST /orders/{orderId}/account/products/{productId}/services

Adds a new service to a product in the order.

Request

POST /orders/{orderId}/account/products/{productId}/services

Request Parameters

orderId - string

The unique order Id. The URI of the order is returned by the POST /orders call.

productId - string

UUID specifying the product

URI Parameters

None.

Request Headers

Content-Type

Required. Set this header to application/json; charset=UTF-8

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.

Request Body

{
  "name": "john.smith1",
  "relatedTo": [ "https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{serviceId}" ],
  "serviceSpecification": "https://api.hostway.com/serviceSpecifications/{serviceSpecificationId}",
  "promoCode": "{promoCode}"
  "billingCycle": 1,
  "attributes": {
    "{attribute-name}": "{attribute-value}",
    ....
  }
}
 

Parameters

name - string

The name of the new service

relatedTo - list (optional)

A list containing other services related in some way to the newly created service. The relatedTo may be omitted, but relationships between some types of services have to be established for the order to be validated or submitted. The list may contain links to other new services in the order and/or a link to an existing service that belongs to the same account. If a link to an existing service is specified, a parent-child relationship will be created between the existing service and the newly-added service.

serviceSpecification - string

Link to the product catalog specification describing the new service

billingCycle - integer

Billing cycle (length of billing period in months) of the service. Allowed values are from 1 to 120

attributes - dictionary (optional)

a dictionary of the new service's attributes values. Each (attribute-name, attribute-value) pair present the service attribute name and its relevant value to be set. The allowed attribute names depends on the serviceSpecification field value. See Service Attributes Structure.

promoCode - string (optional)

A promotion code for the new service promotion codes.

Validation Rules

1. The service specification URL ( https://api.hostway.com/serviceSpecifications/{serviceSpecificationId} ) should point to an existing service.
2. Each service URL ( https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{serviceId} ) from the related services list should point to a valid service already added to the product.
3. The related services list may contain at most one URL to an existing service (ex. https://api.hostway.com/accounts/{accountId}/products/{productId}/services/{serviceId} ) that is open on the account.
4. The service billing cycle should be allowed for the product.
5. The product should support adding the service.

Response

Status Code

Status Code	Error Message	Description
201 Created	-	The service was successfully added to the order.
400 Bad Request	POST data error	Trying to create a service without passing all the required attributes.
	Invalid service specification	Malformed serviceSpecification was passed or the service is not found in the backend.
	Invalid cycle	Trying to add service with wrong billingCycle.
	Invalid relatedTo service ID provided: fake.service	Trying to add a service with invalid relatedTo.
	Product does not support this service	Trying to add service to a product, which doesn't support the service.
	Current service requires being a child service.	The service that can be added only as a child is not added as a child of another service.
	Cannot create domain alias to the same domain name.	Trying to create domain alias to the same domain name.
	Parent service doesn't exist.	Tried to add the service as a child service of an existing service that doesn't exist.
	Parent service is not open.	Tried to add the service as a child service of an existing service that is not open.
401 Unauthorized	This server could not verify that you are authorized to access the document you requested. Either you supplied the wrong credentials (e.g., bad password), or your browser does not understand how to supply the credentials required.	The OwnerId cookie was not specified or is incorrect.
403 Forbidden	Unauthorized: Services failed permission check	The client does not have permissions to add services.
404 Not Found	Resource not found	The order or product doesn't exist.
409 Conflict	Domain-dependent services:
	Cannot create domain alias to the same domain name.	Duplicate domain.
	Email domain alias service: A domain alias would produce impossible to delivery loops
	Domain {domain_name} has circular forwards to alias {alias_name}	There is an email forwarder from the target domain name to a mailbox of the domain alias with the same username
		There is an email forwarder from the domain alias to a mailbox of the target domain name with the same username
502 Bad Gateway	-	Unexpected backend response.

Response Headers

Location

Returned with successful response. Contains the URI of the newly added service and the id of the service.

Response Body

Successful response

201 Created
{
    "serviceId": "00000140735d43640f62c50f007f000000010001",
    "url": "https://api.hostway.com/order/account/products/00000140728b013c52e249a4007f000000010001/services/00000140735d43640f62c50f007f000000010001/"
} 

Note: The service Id will change once the order is provisioned.

Error responses

400 Bad Request - request body is missing some of the required attributes
{
    "badRequest": {
        "guid": "23bf964e-fb93-4bd6-816e-3dcb31b82755",
        "message": "POST data error",
        "code": 400,
        "details": {
            "serviceSpecification": "Required",
            "billingCycle": "Required"
        }
    }
}

400 Bad Request - malformed serviceSpecification was passed or the service is not found in the backend
{
    "computeFault": {
        "guid": "e4443fe7-1139-4078-b407-39d868c02d26",
        "message": "Invalid service specification",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - wrong billingCycle
{
    "computeFault": {
        "guid": "e4443fe7-1139-4078-b407-39d868c02d26",
        "message": "Invalid cycle",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - invalid service was passed as relatedTo
{
    "computeFault": {
        "guid": "e4443fe7-1139-4078-b407-39d868c02d26",
        "message": "Invalid relatedTo service ID provided: fake.service",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - the service is not supported by the product
{
    "computeFault": {
        "guid": "e4443fe7-1139-4078-b407-39d868c02d26",
        "message": "Product does not support this service",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - the service that can be added only as a child was not added as a child of another service
{
    "computeFault": {
        "guid": "e4443fe7-1139-4078-b407-39d868c02d26",
        "message": "Current service requires being a child service.",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - request body provided incorrect attributes
{
    "badRequest": {
        "guid": "5386544b-6dbf-4d21-b22a-879979070c01",
        "message": "POST data error",
        "code": 400,
        "details": {"attributes.serverName": "Required"}
    }
}

400 Bad Request - trying to create domain alias to the same domain name
{
    "computeFault": {
        "guid": "c270f3a1-331f-4736-b420-c006cbdae689",
        "message": "Cannot create domain alias to the same domain name.",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - trying to add domain alias with invalid domain name
{
    "badRequest": {
        "guid": "6321f804-285a-43fb-890a-bbdbc1bd8db3",
        "message": "POST data error",
        "code": 400,
        "details": {"attributes.domain": "Invalid domain name in domain: invalid", "attributes.domain_alias": "Invalid domain name in domain_alias: invalid_alias"}
    }
}

400 Bad Request - trying to specify a relationship to an existing service that doesn't exist
{
    "badRequest": {
        "guid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "message": "Parent service doesn't exist.",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - trying to specify a relationship to an existing service that isn't open
{
    "badRequest": {
        "guid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "message": "Parent service is not open.",
        "code": 400,
        "details": ""
    }
}

401 Unauthorized

This server could not verify that you are authorized to access the document you requested. Either you supplied the wrong credentials (e.g., bad password), or your browser does not understand how to supply the credentials required.

403 Forbidden - the client does not have assess to get the information about the services.
{
    "forbidden": {
        "guid": "d336dd8e-bc52-44f3-b672-9aa2fac7fbf4",
        "message": "Unauthorized: Services failed permission check",
        "code": 403,
        "details": ""
    }
}

404 Not Found - the order or product was not found.
{
    "itemNotFound": {
        "guid": "e1792d8a-5b0a-43ef-adf5-34a0710c8fc5",
        "message": "Resource not found",
        "code": 404,
        "details": ""
    }
}

409 Conflict
{
    "conflict": {
        "guid": "685b8586-c854-4dd8-ae9d-6233fe007a86",
        "message": "Domain ng-test-hwus-drago-140723b.com has circular forwards to alias ng-test-hwus-drago-140723b-alias140814.com",
        "code": 409,
        "details": ""
    }
}

502 Bad Gateway - unexpected error from the backend.
{
    "computeFault": {
        "guid": "8ced5fe7-f6a9-4e8f-8700-cfc9fa15e6ce",
        "timestamp": "2014-09-10 20:59:50",
        "code": 502,
        "errorRefId": "8ced5fe7-f6a9-4e8f-8700-cfc9fa15e6ce"
    }
}

Examples

Create a service with attributes

Request

{
    "name": "ng-test-hwus-test.com",
    "serviceSpecification": "https://api.hostway.com/serviceSpecifications/core.dedserver",
    "billingCycle": 1,
    "attributes": { 
        "serverName": "sampleServerName",
        "serverLocation": "Tampa"
    }
}

Create a service with attributes and make it related to an existing service

Request

{
    "name": "ng-test-hwus-test.com",
    "serviceSpecification": "https://api.hostway.com/serviceSpecifications/core.dedserver",
    "billingCycle": 1,
    "attributes": {
        "serverName": "sampleServerName",
        "serverLocation": "Tampa"
    },
    "relatedTo": ["https://api.hostway.com/accounts/{accountId}/products/{productId}/services/{serviceId}"]
}
 

Create a service with attributes and make it related to another new service in the same order

Request

{
    "name": "ng-test-hwus-test.com",
    "serviceSpecification": "https://api.hostway.com/serviceSpecifications/core.dedserver",
    "billingCycle": 1,
    "attributes": {
        "serverName": "sampleServerName",
        "serverLocation": "Tampa"
    },
    "relatedTo": ["https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{serviceId}"]
}
 

See also

• Orders API
• Common Features
• Service Attributes Structure

blog comments powered by Disqus