Table of Contents

    API

    Transparent Proxy

    Please sign in and we'll assign you a private URL to trace your traffic and help you implement the API.

Scaledo.com Vendors API

Welcome to our API documentation. This api is based on REST principles.

Allowed HTTPs requests

  • GET: Get a resource or list of resources
  • PUT: To update resource
  • POST: To create resource
  • DELETE: to delete resource

Description Of Usual Server Responses

  • 200 OK - the request was successful (some API calls may return 201 instead).
  • 201 Created - the request was successful and a resource was created.
  • 204 No Content - the request was successful but there is no representation to return (i.e. the response is empty).
  • 400 Bad Request - the request could not be understood or was missing required parameters.
  • 401 Unauthorized - authentication failed or user doesn't have permissions for requested operation.
  • 403 Forbidden - access denied.
  • 404 Not Found - resource was not found
  • 500 Internal Server Error - something bad happend
  • 501 Not Implemented - you are calling method that is not implemented

API autentication

We are using basic http authencication with username and password. Please add to all requests "Authorization:" header:

Example: Authorization: Basic aHR0cHdhdGNoOmY=

the string aHR0cHdhdGNoOmY= is base64 encoded version of <username>:<password> Connection is encripted with ssl, so your credentials are safe.

Language

Api supports different languages in validation messages. You can change language with header Accept-Language: en_us. Supported languages are: en_us, sk.

Resource Relations

                           +---------------------+ 
     +-------------+       | BaseServicePrice    |
     | BaseService |       +---------------------+
     +-------------+       | id                  |<--+
  +->| id          |<-----O| baseServiceId       |   |
  |  | name        |       | price               |   |
  |  | ...         |       | currency            |   |
  |  +-------------+       | ...                 |   |
  |                        +---------------------+   |
  |                                                  |
  |  +--------------------+   +----------------------+
  |  | Service            |   |
  |  +--------------------+   |
  |  | id                 |   |   +--------------+ 
  +-O| baseServiceId      |   |   | User         |
     | baseServicePriceId |O--+   +--------------+
     | userId             |O----->| id           |
     | name               |       | login        |
     | uuid               |       | ...          |
     | ...                |       +--------------+
     +--------------------+

BaseService = your product
BaseServicePrice = product pricing
Service = ordered service

Users

GET

/vendor/v1/user

List of clients in your pool.

Pager url parameters:

  • pagesize=20 - limit result, no limit if empty
  • page=1 - set page, starting from 1

Filter url parameters:

  • filter[login]=demo - filter users by login
  • filter[name]=Demo - filter users by name
  • filter[email]=test@example.com - filter users by email
  • filter[openid]=https%3A%2F%2Fscaledo.com%2Fopenid%2F1 - filter by openid url

Exaple of final url: /vendor/v1/user?pagesize=20&page=3&filter[name]=john

Response

200 (OK)
Content-Type: application/json
{
    "items": [
        {
            "id":1,
            "href":"https://scaledo.com/vendor/v1/user/1",
            "openid":"https://scaledo.com/openid/1",
            "createTime":1362660401,
            "login":"demo",
            "name":"Demo 1",
            "email":"demo@test.com",
            "timezone":"Europe/Bratislava",
            "language":"EN"
        }
    ],
    "pager":{
        "page":1,
        "pagesize":null,
        "items":1,
    }
}

GET

/vendor/v1/user/{user-id}

Client detail.

Response

200 (OK)
Content-Type: application/json
{
    "id":1,
    "href":"https://scaledo.com/vendor/v1/user/1",
    "openid":"https://scaledo.com/openid/1",
    "createTime":1362660401,
    "login":"demo",
    "name":"Demo 1",
    "email":"demo@test.com",
    "timezone":"Europe/Bratislava",
    "language":"EN",
    "country": "SK"
}

Products

GET

/vendor/v1/baseService

List of products in your pool

Pager url parameters:

  • pagesize=20 - limit result, no limit if empty
  • page=1 - set page, starting from 1

Response

200 (OK)
Content-Type: application/json
{ "items": [
        {
            "id":1,
            "href": "https://scaledo.com/vendor/v1/baseService/1",
            "name":"my product",
            "parameters":[
                {
                    "name":"space",
                    "label":"Storage space",
                    "unit":"MB"
                }
            ],
            "permissions":[
                {
                    "name":"storage",
                    "label":"Storage Access",
                    "parent":null
                }
            ]
        }
    ],
    "pager":{
        "page":1,
        "pagesize":null,
        "items":1,
    }
}

GET

/vendor/v1/baseService/{base-service-id}

Detail of product

Response

200 (OK)
Content-Type: application/json
{
    "id": 1,
    "href": "https://scaledo.com/vendor/v1/service/1",
    "name":"my product",
    "parameters":[
        {
            "name":"asd",
            "label":"adsasd"
        }
    ],
    "permissions":[
        {
            "name":"storage",
            "label":"Storage Access",
            "parent":null
        }
    ]
}

Product prices

Parameters:

  • baseServiceId - integer, base service id
  • price - string - equation or float number
    • equation is written in syntax http://linux.die.net/man/1/bc.
    • you can use service parameter ex. 0.05*parameter_storage (5 cents for every MB), just prefix the name with parameter_
  • currency- 'EUR' or 'USD'
  • identifier - string max. 255 chars - this can be used to identify pricing plan, for ex. 'basic', 'permium'...
  • period - integer from 1 to 31 - recurring period
  • periodLength - string 'DAY', 'MONTH' or 'YEAR'
  • trialPeriod - integer from 1 to 31
  • trialPeriodLength - string 'DAY', 'MONTH' or 'YEAR'
  • desc - string
  • paymentAfter - boolean
  • active - boolean

GET

/vendor/v1/baseServicePrice

List of all prices in your pool

Pager url parameters:

  • pagesize=20 - limit result, no limit if empty
  • page=1 - set page, starting from 1

Response

200 (OK)
Content-Type: application/json
{
    "items": [
        {
            "id":1,
            "href":"https://scaledo.com/vendor/v1/baseServicePrice/1",
            "baseService":{
                "id":1,
                "href":"https://scaledo.com/vendor/v1/baseService/1",
                "name":"my product"
            },
            "price":"parameter_storage*0.01",
            "currency":"EUR",
            "identifier":"standard",
            "period":1,
            "periodLength":"MONTH",
            "trialPeriod":0,
            "trialPeriodLength":"MONTH",
            "desc":"description here",
            "paymentAfter":0,
            "active":1
        }
    ],
    "pager":{
        "page":1,
        "pagesize":null,
        "items":1,
    }
}

GET

/vendor/v1/baseServicePrice/{base-service-price-id}

Detail of price

Response

200 (OK)
Content-Type: application/json
{
    "id":1,
    "href":"https://scaledo.com/vendor/v1/baseServicePrice/1",
    "baseService":{
        "id":1,
        "href":"https://scaledo.com/vendor/v1/baseService/1",
        "name":"my product"
    },
    "price":"parameter_storage*0.01",
    "currency":"EUR",
    "identifier":"standard",
    "period":1,
    "periodLength":"MONTH",
    "trialPeriod":0,
    "trialPeriodLength":"MONTH",
    "desc":"description here",
    "paymentAfter":0,
    "active":1
}

PUT

/vendor/v1/baseServicePrice/{base-service-price-id}

currently disabled

Update price

Available parameters to update:

baseServiceId price currency identifier period periodLength trialPeriod trialPeriodLength desc paymentAfter active

Response

200 (OK)
Content-Type: application/json
{
    "status": "updated",
    "errors":[],
}

POST

/vendor/v1/baseServicePrice

currently disabled

Create price

Required parameters:

baseServiceId, price, currency

Response

200 (OK)
Content-Type: application/json
{
    "status": "created",
    "errors":[],
    "href": "/vendor/v1/baseServicePrice/{base-service-price-id}"
}

DELETE

/vendor/v1/baseServicePrice/{base-service-price-id}

currently disabled

Delete price

Response

200 (OK)
Content-Type: application/json
{
    "status": "deleted"
}

Ordered services

GET

/vendor/v1/service

List of orderes services

Pager url parameters:

  • pagesize=20 - limit result, no limit if empty
  • page=1 - set page, starting from 1

Filter url parameters

  • filter[name]=test - filter by name
  • filter[uuid]=587759bc-fcbc-4313-9d3f-2868f6ef1e0d - filter by uuid
  • filter[user][id]=1 - filter by owner user id
  • filter[user][login]=test - filter by owner user login
  • filter[user][email]=test@example.com - filter by owner user email
  • filter[price][id]=1 - filter by price id
  • filter[baseService][id]=1 - filter by Base Service id

Exaple of final url: /vendor/v1/service?pagesize=20&page=1&filter[user][id]=1

Response

200 (OK)
Content-Type: application/json
{
    "items": [
        {
            "id":1,
            "href":"https://scaledo.com/vendor/v1/service/1",
            "createTime":1362662101,
            "name":"test",
            "uuid":"587759bc-fcbc-4313-9d3f-2868f6ef1e0d",
            "lastPayedPrice":12.5,
            "nextPaymentPrice":12.5,
            "discount":0.0,
            "rewritePrice":null,
            "rewritePeriod":null,
            "rewritePeriodLength":null,
            "deactivate": false,
            "deactivateTime": null,
            "deleted": false,
            "deletedTime": null,
            "free": false,
            "prepaidUntil": 1385545300,  // null in trial period
            "user":{
                "id":1,
                "href":"https://scaledo.com/vendor/v1/user/1",
                "openid": "https://scaledo.com/openid/1",
                "createTime":1362660401,
                "login":"demo",
                "name":"Demo 1",
                "email":"demo@test.com",
                "timezone":"Europe/Bratislava",
                "language":"EN",
            },
            "price":{
                "id":1,
                "href":"https://scaledo.com/vendor/v1/base-service-price/1",
                "price":"parameter_storage*0.01",
                "currency":"EUR",
                "identifier":"standard",
                "period":1,
                "periodLength":"MONTH",
                "trialPeriod":0,
                "trialPeriodLength":"MONTH",
                "desc":"description here",
                "paymentAfter":0,
                "active":1
            },
            "baseService":{
                "id":1,
                "href":"https://scaledo.com/vendor/v1/service/1",
                "name":"my product"
            },
            "parameters":[
                {
                    "value":500,
                    "name":"first_parameter",
                    "label":"My label",
                    "unit":"MB"
                }
            ]
        }
    ],
    "pager":{
        "page":1,
        "pagesize":null,
        "items":1,
    }
}

GET

/vendor/v1/service/{service-id}

Ordered service

Response

200 (OK)
Content-Type: application/json
{
    "id":1,
    "href":"https://scaledo.com/vendor/v1/service/1",
    "createTime":1362662101,
    "name":"test",
    "uuid":"587759bc-fcbc-4313-9d3f-2868f6ef1e0d",
    "lastPayedPrice":12.5,
    "nextPaymentPrice":12.5,
    "discount":0.0,
    "rewritePrice":null,
    "rewritePeriod":null,
    "rewritePeriodLength":null,
    "deactivate": false,
    "deactivateTime": null,
    "deleted": false,
    "deletedTime": null,
    "free": false,
    "prepaidUntil": 1385545300,  // null in trial period
    "user":{
        "id":1,
        "href":"https://scaledo.com/vendor/v1/user/1",
        "openid": "https://scaledo.com/openid/1",
        "createTime":1362660401,
        "login":"demo",
        "name":"Demo 1",
        "email":"demo@test.com",
        "timezone":"Europe/Bratislava",
        "language":"EN",
    },
    "price":{
        "id":1,
        "href":"https://scaledo.com/vendor/v1/baseServicePrice/1",
        "price":"parameter_storage*0.01",
        "currency":"EUR",
        "identifier":"standard",
        "period":1,
        "periodLength":"MONTH",
        "trialPeriod":0,
        "trialPeriodLength":"MONTH",
        "desc":"description here",
        "paymentAfter":0,
        "active":1
    },
    "baseService":{
        "id":1,
        "href":"https://scaledo.com/vendor/v1/service/1",
        "name":"my product"
    },
    "parameters":[
        {
            "value":500,
            "name":"first_parameter",
            "label":"My label",
            "unit":"MB"
        }
    ],
    "grantedToUsers":
    [
        {
            "id": 2,
            "href": "https://scaledo.com/vendor/v1/user/2",
            "openid": "https://scaledo.com/openid/2",
            "createTime": 1360537200,
            "login": "login",
            "name": "name",
            "email": "test@example.comn",
            "timezone": "Europe/Bratislava"
        }
    ]
}

PUT

/vendor/v1/service/{service-id}

Update ordered service

Available parameters to update:

  • baseServicePriceId - integer
  • name - string
  • rewritePrice - float or null - if set, price form baseServicePrice will be ignored
  • rewritePeriod - integer from 1 to 31
  • rewritePeriodLength - string 'DAY', 'MONTH' or 'YEAR'
  • discount - float - from 0 to 1, final price = price - discount * price
  • parameters{"param_name": value } - array or parameters

Response

200 (OK)
Content-Type: application/json
{
    "status": "updated",
    "errors":[]
}

Response

400 (Bad Request)
Content-Type: application/json
{
    "status": "input_error",
    "errors": {
        "rewritePeriod": [
            "Rewrite Period is too big (maximum is 31)."
        ],
        "baseServicePriceId": [
            "wrong reference"
        ]
    }
}