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

From Hostway API Documentation
Revision as of 12:29, 16 November 2016 by Corinne.chui (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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

Adds a new service to a product in the order.

Contents


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}" ],
  "associatedTo": [ "https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{serviceId}" ],
  "serviceSpecification": "https://api.hostway.com/serviceSpecifications/{serviceSpecificationId}",
  "promoCode": "{promoCode}"
  "billingCycle": 1,
  "quantity": 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
quantity - integer (optional)
Quantity of the service. Must be greater than 0. It is 1 by default. Quantity greater than 1 only allowed for services configured to support multiple quantities when ordering.
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.
associatedTo - list (optional)
A list containing other services that are associated in some way to the newly created service. 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 and product. Adding a service to this list will not alter existing or create new parent-child relationships between the existing service and the newly-added service. In most cases the list may be empty unless otherwise stated.

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.
  6. Each service URL from the associated services list should point to a valid service already added to the product.
  7. Any associated service that already exists on the account must be open.

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 quantity Trying to add service with invalid quantity input. It should be a number greater than 0.
Product does not support quantity Trying to set quantity on service that is not configured to support multiple units.
Invalid relatedTo service ID provided: fake.service Trying to add a service with invalid relatedTo.
Invalid associatedTo service ID: fake.service Trying to add a service with invalid associatedTo.
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 quantity
{
    "computeFault": {
        "guid": "e4443fe7-1139-4078-b407-39d868c02d26",
        "message": "Invalid quantity",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - unsupported quantity
{
    "computeFault": {
        "guid": "e4443fe7-1139-4078-b407-39d868c02d26",
        "message": "Product does not support quantity",
        "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": ""
    }
}

400 Bad Request - trying to specify an association to an existing service that doesn't exist
{
    "badRequest": {
        "guid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "message": "Invalid associatedTo service ID: xxxxx",
        "code": 400,
        "details": ""
    }
}

400 Bad Request - trying to specify an association to an existing service that isn't open
{
    "badRequest": {
        "guid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "message": "Associated 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}"]
}

Create a service with quantity but without 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.hardware.memory",
    "billingCycle": 1,
    "quantity": 4,
    "relatedTo": ["https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{serviceId}"]
}

Create a service and make it associated to an existing service

Request 

{
    "name": "ng-test-hwus-test.com",
    "serviceSpecification": "https://api.hostway.com/serviceSpecifications/core.dedicatedserver.hardware.disk.500gb",
    "billingCycle": 1,
    "quantity": 4,
    "associatedTo": ["https://api.hostway.com/accounts/{accountId}/products/{productId}/services/{serviceId}"]
}

Create a service and make it associated to another new service in the same order

Request 

{
    "name": "ng-test-hwus-test.com",
    "serviceSpecification": "https://api.hostway.com/serviceSpecifications/core.dedicatedserver.hardware.disk.500gb",
    "billingCycle": 1,
    "quantity": 4,
    "associatedTo": ["https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{serviceId}"]
}

Create a service and make it associated to two other new services in the same order

Request 

{
    "name": "ng-test-hwus-test.com",
    "serviceSpecification": "https://api.hostway.com/serviceSpecifications/core.dedicatedserver.hardware.diskcontroller.sataraid",
    "billingCycle": 1,
    "quantity": 4,
    "associatedTo": [
        "https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{service1Id}",
        "https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{service2Id}"
    ]
}

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

Request 

{
    "name": "ng-test-hwus-test.com",
    "serviceSpecification": "https://api.hostway.com/serviceSpecifications/core.dedicatedserver.hardware.disk.500gb",
    "billingCycle": 1,
    "quantity": 4,
    "relatedTo": ["https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{service1Id}"],
    "associatedTo": ["https://api.hostway.com/orders/{orderId}/account/products/{productId}/services/{service2Id}"]
}

See also


blog comments powered by Disqus

Retrieved from "http://docs.hostway.com/index.php?title=Orders-orderId-account-products-productId-services:POST&oldid=2589"
Personal tools
Namespaces
Variants
Actions
APIs
Navigation
Toolbox