V Cloud

V Cloud Platform API Guide

Overview

We provide api for querying service provider, service category, service type information and order information. V Cloud market command line and merchant endpoint will interact with the platform through these apis.

  1. Provider Information
  2. Service Category Information
  3. Service Type Information
  4. Upload Service Template
  5. Order Information

Create Provider Information

It is highly recommended to use service template for service registration.

POST /api/v1/service/provider

Request Body

{
	"name": "provider-name",
	"id": "provider-name",
	"walletAddress": "ATxxxxxxxxxxxxxxxxxxaaddfsawrEDAs",
	"apiHost": "some-ip-domain-host",
	"category2ID": {
		"category-name-1": "category-id-1"
	}
}
Field Name Type Required Explanation
name string True provider-name
id string True the same as provider name, provider id
walletAddress string True provider wallet address
apiHost string True api host for user service
category2ID dict False mapping of category name to category id

Query Provider Information

GET /api/v1/service/provider?

Fields of Query Parameters

Field Name Type Explanation
id string provider id
name string provider name, the same as above
walletAddress string get provider info by walletAddress
current number current page number
pageSize number size of a page information

Response

Status: 200 OK

{
    "list": [
        {
            "name": "provider-name",
            "walletAddress": "ATzxxxxxxxxxxxxxxxxxxxxxxebud",
            "signAddress": "ATzxxxxxxxxxxxxxxxxxxxxxxebud",
            "id": "provider-name",
            "apiHost": "http://localhost:3001",
            "category2ID": {
                "Container-Service": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
                "Container-Service-Working": "a242e27a-5bba-4e2c-a7f4-92cced21ff71"
            }
        }
    ],
    "pagination": {
        "total": 1,
        "current": 1,
        "pageSize": 10
    }
}

Fields of Provider Item in list

The list contains an array of provider information dict. The following is the fields for each provider.

Field Name Type Explanation
name string name of a provider, should be unique
walletAddress string vsys wallet address of the provider
signAddress string the address to sign the request when provider uploads service template
id string provider id, the same as name field，should be unique
apiHost string provider SDK server host for retrieving user service information
category2ID dict matching between category name and category id
Fields of pagination
Field Name Type Explanation
total number total number of providers
current number current page of provider information
pageSize number page size

Get Provider Information

GET  /api/v1/service/provider/:id

Response

Status: 200 OK

{
    "name": "v-kube-service",
    "walletAddress": "ATxxxxxxxxxxxxxxxxxxxxxebud",
    "signAddress": "ATxxxxxxxxxxxxxxxxxxxxxebud",
    "id": "v-kube-service",
    "apiHost": "http://localhost:3001",
    "category2ID": {
        "Container-Service": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
        "Container-Service-Working": "a242e27a-5bba-4e2c-a7f4-92cced21ff71"
    }
}

The field explanation please refer to provider fields

Create Service Category

It is highly recommended to use service template for service registration.

POST /api/v1/service/category

Request Body

{
	"provider": "provider-name",
	"name": "category-name",
	"serviceOptions": {
		"custom-field-1": "custom-value-1"
	},
	"description": "some-description",
	"name2ID": {
		"service-type-name-1": "service-type-id-1"
	}
	"apiHost": "service-type-backup-api-host"
}
Field Name Type Required Explanation
provider string True provider that this service category belongs to
name string True service category name, it is unique under a provider
serviceOptions dict False service options that this service category provides
description string False description for user to understand service that this category provides.
name2ID dict False mapping of service type name to service id
apiHost string False backup api host for service type under this category

Query Service Category Information

GET /api/v1/service/category?

Fields of Query Parameter

Field Name Type Explanation
ids string[] a list of id string
provider string provider name
name string category name
current number current page number
pageSize number page size

Response

Status: 200 OK

{
    "list": [
        {
            "categoryID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
            "provider": "provider-name",
            "name": "Container-Service",
            "serviceOptions": {
                "custom-options-1": [
                    "value-1",
                    "value-2",
                    "value-3",
                ],
                "custom-options-2": [
                    "value-1",
                    "value-2"
                ]
            },
            "description": "Deploy docker images to k8s cluster",
            "name2ID": {
                "Container Service": "af91f22a-ffcf-4e8c-9a83-f1f6bcc8bf6e"
            },
            "apiHost": ""
        },
    ],
    "pagination": {
        "total": 2,
        "current": 1,
        "pageSize": 10
    }
}
Fields of service category item in list
Field Name Type Explanation
categoryID string service category id
provider string service provider that this category belongs to
name string service category name, should be unique under the provider
serviceOptions dict a dictionary of string to string list mapping holding service option fields and corresponding available values
description string service category description
name2ID dict a dictionary of string to string mapping for service type name and id
apiHost string a backup host for service type under this service category

The pagination field explanation please refer to pagination fields

Get Service Category

GET /api/v1/service/category/:id

Response

Status: 200 OK

{
    "categoryID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
    "provider": "provider-name",
    "name": "Container-Service",
    "serviceOptions": {
        "custom-options-1": [
            "value-1",
            "value-2",
            "value-3",
        ],
        "custom-options-2": [
            "value-1",
            "value-2"
        ]
    },
    "description": "Deploy docker images to k8s cluster",
    "name2ID": {
        "Container Service": "af91f22a-ffcf-4e8c-9a83-f1f6bcc8bf6e"
    },
    "apiHost": ""
}

The field explanation is the same as the item response from querying. For detail, please refer to service category fields

Create Service Type

POST /api/v1/service/category

Request Body

{
	"name": "service-type-name",
	"durationToPrice": [
		{
			"price": 100,
			"charingOptions": {
				"custom-field-1": "custom-value"
			},
			"duration": {
				1: 1
				20: 0.99
				100: 0.89
			}
		}
	],
	"provider": "provider-name",
	"refundable": true,
	"categoryID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
	"category": "category-name-1",
	"serviceOptions": {
		"custom-field-1": [
			"custom-value-1",
			"custom-value-2",
			"custom-value-3"
		]
	},
	"serviceAPI": {
		"start": "some-lua-script",
		"stop": "some-lua-script",
		"refund": "some-lua-script",
		"normal": {
			"api-name": "/api/v1/some/function"
		},
		"secret": {
			"api-name": "/api/v1/some/secret/func"
		}
	},
	"description": "go-charger",
	"apiHost": "11.22.88.4"
}
Field Name Type Required Explanation
name string True service type name, should be unique under a service category
durationToPrice object True base price with service duration to discount faction.
provider string True provide name
refundable bool True if this service type is able to refund
categoryID string True service category id
category string True service category name
serviceOptions dict False service options for this service type
serviceAPI object False available api for user after buying the service
description string False service type description
apiHost string False api host for user to use service

Fields of durationToPrice

Field Name Type Required Explanation
price number False price value per hour
chargingOptions map[string]string False options that make price different
duration map[int]float False service duration to discount faction

Fields of serviceAPI

Field Name Type Required Explanation
start string False lua script for service starting, script has to be url encoded.
stop string False lua script for service ending, script has to be url encoded.
refund string False lua script for custom service refund, script has to be url encoded.
normal map[string]string False api name to api path mapping. It is for user who bought the service.
secret map[string]string False api name to api path mapping. It is for user who bought the service. It needs authentication

Query Service Type Information

GET /api/v1/service/type?

Fields of Query Parameter

Field Name Type Explanation
ids string[] a list of id string
provider string provider name
category string get service type in this service category name
name string get service type by name
minPrice float get service type that its base price is larger than minPrice
maxPrice float get service type that its base price is smaller than maxPrice
current number current page
pageSize number page size

Response

Status: 200 OK

{
    "list": [
        {
            "id": "af91f22a-ffcf-4e8c-9a83-f1f6bcc8bf6e",
            "name": "Container Service",
            "durationToPrice": [
                {
                    "price": 100,
                    "chargingOptions": {
                        "custom-options-1": "value-1"
                    },
                    "duration": {
                        "100": 0.9,
                        "200": 0.85
                    }
                },
                {
                    "price": 200,
                    "chargingOptions": {
                        "custom-options-1": "value-2"
                    },
                    "duration": {
                        "100": 0.9,
                        "200": 0.85
                    }
                },
                {
                    "price": 500,
                    "chargingOptions": {
                        "custom-options-1": "value-3"
                    },
                    "duration": {
                        "100": 0.9,
                        "200": 0.85
                    }
                },
            ],
            "provider": "provider-name",
            "refundable": true,
            "categoryID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
            "category": "Container-Service",
            "serviceOptions": {
                "custom-options-1": [
                    "value-1",
                    "value-2",
                    "value-3",
                ],
                "custom-options-2": [
                    "value-1",
                    "value-2"
                ]
            },
            "serviceAPI": {
                "start": "",
                "stop": "",
                "refund": "",
                "normal": {},
                "secret": {}
            },
            "description": "Documentation for user to use this service: http:xxxxxxx",
            "apiHost": ""
        },
    ],
    "pagination": {
        "total": 1,
        "current": 1,
        "pageSize": 10
    }
}

Fields of service type item in list

Field Name Type Explanation
id string service type id
name string service type name, should be unique among a category
durationToPrice object[] list of different prices for different charging options
provider string provider name that this service type belongs to
refundable bool if this service type supports refund
categoryID string categoryID that this service type belongs to
serviceOptions dict available service options for this service type, referring to service category fields for detail
serviceAPI object supportted api service. User only can see normal and secret field.
description string service type description containing payment procedure and usage tutorial information
apiHost string api host that provides this service

Fields in a item of durationToPrice list

Field Name Type Explanation
price number base price for this service (per hour)
chargingOptions dict the service options that determine the base price
duration dict service time and corresponding discount factor

Fields of serviceAPI

Field Name Type Explanation
normal dict usable apis that do not need authentication
secret dict usable apis that need authentication

Upload Service Template

GET /api/v1/template/add

The server will read the request body for service template and create service information. Please refer to service template explanation for template details.

Query Order Information

GET /api/v1/order?

Fields of Query Parameter

Field Name Type Explanation
id string order id
startFrom number starting search timestamp for order
endAt number ending search timestamp for order
serviceID string orders that are related to this service id
service string orders that are related to this service name
address string orders that are related to this address
recipient string orders that are related to this provider address
statuses[] string[] orders that have these order statuses
serviceActivated bool if the user service is activated
userServiceStartFrom number starting search timestamp for user service in order
userServiceEndAt number ending search timestamp for user service in order
serviceStatuses[] string[] orders that have these user service statuses
current number current page number
pageSize number page size

Response

{
    "list": [
        {
            "createdAt": 1622793531,
            "updatedAt": 1622801453,
            "duration": 1,
            "serviceExpiredDate": 0,
            "amount": 9.5,
            "amountPaid": 9.5,
            "serviceID": "53bc15ca-e6f8-42ef-a814-8c5f14d22b79",
            "service": "xxxxx Service",
            "serviceCategoryID": "a242e27a-5bba-4e2c-a7f4-92cced21ff71",
            "provider": "xxxx provider",
            "address": "AU2xxxxxxxxxxxxxxxxxxxxPXGp5sj",
            "recipient": "ATxxxxxxxxxxxxxxxxxxiiEouTebud",
            "id": "d9ae2543-3185-4839-bc56-f885aa879881",
            "serviceOptions": {
                "custom-option-1": "value-1",
                "custom-option-2": "value-1"
            },
            "status": "OrderFiled",
            "lastPaymentTS": 1622793555,
            "PaidTS": 1622793555,
            "FiledTS": 1622793555,
            "completeTS": 1622801452,
            "refundTS": 0,
            "publicKey": "",
            "serviceActivated": false,
            "serviceActivateTS": 1622793555,
            "endAt": 1622801341,
            "serviceStatus": "ServiceDone",
            "serviceRunningTS": 1622797741,
            "serviceAbortTS": 0,
            "serviceDoneTS": 1622801452,
            "magic": ""
        }
    ],
    "pagination": {
        "total": 1,
        "current": 1,
        "pageSize": 10
    }
}

Fields of order item in list

Field Name Type Explanation
createdAt number the created timestamp in database
updatedAt number last updated timestamp in database
duration number time for the service to run in hour
serviceExpiredDate number user defined service ending timestamp
amount number total amount to pay for using service
amountPaid number remaining amount to pay
serviceID string service id of this order
service string service name
serviceCategoryID string service category id
provider string the provider provides this service
address string user address that creates this order
recipient string provider address
id string order id
serviceOptions object refers to service category fields
status string order status
lastPaymentTS numner user's last payment timestamp
paidTS number user's finishing payment timestamp
filedTS number timestamp of provider files service secret token
completeTS number order finished timestamp
refundTS number timestamp of order refund
publicKey number public key to encrypt secret token during filing
serviceActivated bool if the service status is usable
serviceActivatedTS number timestamp of service status is activated
endAt number user service ending timestamp
serviceStatus string user service status
serviceRunningTS number service starts running timestamp
serviceAbortTS number service abort timestamp
serviceDoneTS number service done timestamp
magic string DEPRECIATED

Get Order Information

GET /api/v1/order/id/:id

Please refer to order fields for response detail.

Create Order Information

User needs to sign their request using VSYS wallet address private key so that they can make a successful request.

Request Body

{
	"amount": 10.0,
	"address": "ATxxxxxxxxxxxxxsdflkjkdkdkdk",
	"duration": 1,
	"serviceExpiredDate": 16903049433,
	"serviceID": "0ac3d8e1-d803-4af3-8cd2-f87939131b37",
	"serviceOptions": {
		"custom-field": "value-1"
	}
}
Field Name Type Required Explanation
amount float True the amount that user buys the service
address string False the address that buys the service
duration number False the duration of the service, Must have value for one of the field, duration &serviceExpiredDate
serviceExpiredDate number False the end timestamp when user want to stop the service.
serviceID string True service id
serviceOptions dict False user selected service options
Last Updated: 6/8/2021, 7:50:49 AM