Previous topic

Core Types

Next topic

Application

DOCUMENTATION
Last updated 11-Aug-2016

Resource

The Resource type is the base type for any resource operations.

Resource schema: download

{
  "apsVersion": "2.0",

  "id": "http://aps-standard.org/types/core/resource/1.0",
  "name": "Resource",

  "operations": {
    "provision": {
      "name": "provision",
      "verb": "POST",
      "path": "/",
      "static": true,
      "access": {
          "admin": true,
          "owner": true,
          "referrer": false
      }
    },

    "retrieve": {
      "name": "retrieve",
      "verb": "GET",
      "path": "/",
      "access": {
          "admin": true,
          "owner": true,
          "referrer": true
      }
    },

    "configure": {
      "name": "configure",
      "verb": "PUT",
      "path": "/",
      "parameters": {
        "new": {
          "type": "self",
          "required": true,
          "kind": "body"
        }
      },
      "access": {
          "admin": true,
          "owner": true,
          "referrer": false
      }
    },

    "unprovision": {
      "name": "unprovision",
      "verb": "DELETE",
      "path": "/",
      "access": {
          "admin": true,
          "owner": true,
          "referrer": false
      }
    }
  },

  "structures": {

    "Counter": {
      "type": "object",
      "properties": {
        "usage": { "type": "integer" },
        "limit": { "type": "integer" }
      }
    },

    "Limit": {
      "type": "object",
      "properties": {
        "limit": { "type": "integer" }
      }
    },

    "Usage": {
      "type": "object",
      "properties": {
        "usage": { "type": "integer" }
      }
    },

    "NotificationSource":
    {
    	"type": "object",
    	"properties": {
            "type": {
                "type": "string",
                "format": "uri",
                "description": "APS Type of source resources"
            },
            "id": {
                "type": "string",
                "description": "Resource which is source of event"
            }
    	}
    },
    
    "Notification": {
      "type": "object",
      "description": "Event notification structure",

      "properties": {
        "type": {
           "type": "string",
           "format": "uri",
           "required": true,
           "description": "Type of event (URI)"
        },
        "time": {
           "type": "string",
           "format": "date-time",
           "description": "Date-time when event happens"
        },
        "serial": {
           "type": "number",
           "description": "Serial number of event (incrementing)"
        },
        "source": {
           "type": "NotificationSource",
           "description": "Resource originating the event"
        }
      }
    }
  }
}

Resource Properties

The base resource does not have any properties.

Resource Operations

The resource operations are basic for all APS resources and are described in details in resource operations.

Provision

See Provisioning Resources

Configure

See Resource Configuration

Unprovision

See Unprovisioning Resources

Resource Structures

A few resource structures are defined in a core resource.

  • Limit - a type defining a limiting parameter. It is represented by a structure with a single property limit

    ...
    "diskspace": {
       "limit": 10000000
    }
    ...
    
  • Usage - a type defining a usage report counter

    ...
    "diskspace": {
       "usage": 1234567
    }
    ...
    
  • Counter - a combination of limit and usage together

    ...
    "diskspace": {
       "limit": 10000000,
       "usage": 1234567
    }
    ...
    

Besides being usual resource properties these types give a hint to an integrating product to provide limits or/and get usage from a particular resource counter. A situation when usage exceeds a set limit is treated as abnormal and must not be allowed by an application.

In an APS Type definition a diskspace counter like in the last example above will look like:

{
   "id": "http://webhosting.example.com/types/version/1.0",
   "implements": [
      "http://aps-standard.org/types/core/resource/1.0"
   ],

   "properties": {
      "siteName": {
         "type": "string",
         "title": "WebSite Name"
      },

      "diskspace": {
         "type": "http://aps-standard.org/types/core/resource/1.0#Counter",
         "title": "Website diskspace",
         "unit": "kb"
      }
   }
 }

The following units are supported in definitions of APS Types that include the abovementioned structures:

kb, mb, gb, unit, item, mb-h, mhzh, item-h

Note

unit and item have the same functions and the both units are kept for compatibility with Odin Service Automation resources.

mb-h, mhzh, item-h are used as the units for additive resources in hours.

The application is responsible for filling in the usage fields of structures on retrieve requests.

If a Limit or Counter type is used and no limit is provided as the configuration then the value is unlimited.

If the application author wants to cover a case when a resource is prohibited (not allowed), the author should make the whole resource optional, compare:

Disabled diskspace usage:

{
   "siteName": "mysite.com",
}

Versus unlimited case:

{
   "siteName": "mysite.com",
   "diskspace": {}
}

And usage reporting is still allowed for the unlimited case:

{
   "siteName": "mysite.com",
   "diskspace": {
      "usage": 123456
   }
}