Table of Contents

    API

    Mock Server

    Use this URL to access a mockup of the API server. Your traffic will be recorded and compared to the documentation. You'll find your traffic analysis in the inspector or directly here in the documentation, right next to each resource.

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"
        ]
    }
}