Rate Schedule API
The purpose of this API is to create, update and delete rate schedules and their lines. Note that this API does not support creations, updates or deletes of default time periods. To load rate schedules and/or lines using this API, the default time period(s) must be created beforehand. Refer to the Rate Schedules chapter of the Rates and Adjustments implementation guide for more information on the related model.
Requests
Create a rate schedule
Use the POST method to create a new rate schedule. The payload must be sent to the collection resource of the rate schedule API.
| Section "Discoverability" in Concepts describes how to discover a collection resource from the root URI. |
| This API uses HTTP status codes as defined in Response Messages. |
The link to the collection resource for this generic resource is available in the root resource of all Generic HTTP APIs under the name "rateschedules" and may look like this:
http://<hostname>:<port>/<contextRoot>/generic/rateschedules
Example payload:
{
"code": "<code>",
"amountInterpretation": "<amountInterpretation (C or Y)>",
"scheduleDefinition":
{
"code": "<scheduleDefinitionCode>"
},
"currency":
{
"code": "<currencyCode>"
}
}
| The payloads presented in this section are just examples. Please use the Swagger metadata to find out what all is possible. |
When the POST is successful, the system will return a resource representation of the created rate schedule like this:
{
"id": ,
"code": "<code>",
"amountInterpretation": "<amountInterpretation C or Y>",
... more attributes ...
"links": [
{
"href": "http://<hostname>:<port>/<contextRoot>/generic/rateschedules/",
"rel": "self"
}
],
"rateScheduleLineList": [
{
"startDate": "<startDate of default time period 1>",
"links": [
{
"href": "http://<hostname>:<port>/<contextRoot>/generic/rateschedules/<rate schedule id>/rateschedulelines/defaulttimeperiod/<defaultTimePeriodId 1>",
"rel": "canonical"
},
{
"rel": "oi:definition",/
"href": "http://<hostname>:<port>/<contextRoot>/generic/rateschedules/<rate schedule id>/rateschedulelines/definition"
}]
},
{
"startDate": "<startDate of default time period 2>",
"links": [
{
"href": "http://<hostname>:<port>/<contextRoot>/generic/rateschedules/<rate schedule id>/rateschedulelines/defaulttimeperiod/<defaultTimePeriodId 2>",
"rel": "canonical"
},
{
"rel": "oi:definition",/
"href": "http://<hostname>:<port>/<contextRoot>/generic/rateschedules/<rate schedule id>/rateschedulelines/definition"
}]
}
]
}
The resource representation has a property "rateScheduleLineList" with links for each defined default time period. Those links can be followed to retrieve, create, update or delete lines for that time period and rate schedule. For more details, see sections below.
The "oi:definition" has the usual functionality. Instead of returning the internal datamodel, it however represents the definition of the dimensions of the rate schedule. For example, when a rate schedule is based on schedule definition AGE_MED_COND that has dimensions age (numeric) and medicalCondition (alphanumeric), then the link of type "oi:definition" returns:
{
"AGE_MED_COND": {
"type": "object",
"properties": {
"amount": {
"type": "object",
"properties": {
"value": {
"type": "number",
"xml": {
"attribute": true
},
"minimum": 0,
"maximum": 9999999999.99
}
}
},
"functionDynamicLogic": {
"$ref": "http://<hostname>:<port>/<contextRoot>/generic/dynamicLogic/definition"
},
"age": {
"type": "object",
"properties": {
"valueFrom": {
"type": "number",
"xml": {
"attribute": true
},
},
"valueTo": {
"type": "number",
"xml": {
"attribute": true
},
}
}
}
"medicalCondition": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000
}
}
}
}
In general, the definition resource is like this:
{
"type": "object",
"properties": {
"amount": {
"type": "object",
"properties": {
"value": {
"type": "number",
"xml": {
"attribute": true
},
"minimum": 0,
"maximum": 9999999999.99
}
}
},
"functionDynamicLogic": {
"$ref": "http://<hostname>:<port>/<contextRoot>/generic/dynamicLogic/definition"
},
"<amountField>": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"xml": {
"attribute": true
}
},
"valueAmount": {
"type": "number",
"xml": {
"attribute": true
},
"minimum": -9999999999.99,
"maximum": 9999999999.99
}
}
},
"<charField>": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000
},
"<charFlexCodeField>": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000,
"x-oi-dyn-flex-link": "<URL>"
},
"<charRangeField>": {
"type": "object",
"properties": {
"valueFrom": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000
},
"valueTo": {
"type": "string",
"xml": {
"attribute": true
},
"maxLength": 1000
}
}
},
"<dateField>": {
"type": "string",
"format": "date",
"xml": {
"attribute": true
}
},
"<numberField>": {
"type": "number",
"xml": {
"attribute": true
}
}
}
}
Retrieve rate schedules
Existing rate schedule(s) can be retrieved using the Query API against the collection resource, using the GET operation.
Example URL:
http://<hostname>:<port>/<contextRoot>/generic/rateschedules?q=code.eq('<some code>')
The resource representation is similar to the one returned after a POST (there are some differences because it is possible to return multiple rate schedules at once), including the rateScheduleLineList section with the links to lines.
{
"offset": 0,
"count": 2,
"hasMore": true,
"limit": 50,
"items": [
{
"id": ,
"code": "<code>",
... other rate schedule properties, including rateScheduleLineList
},
{...}
]
}
Update a rate schedule
Updating the rate schedule is done with the PUT operation against the singular resource. The singular resource is returned either from a POST or a GET operation. The payload is identical to the payload of the POST operation. The PUT operation returns the updated version of the resource.
Add, update and delete rate schedule lines
Operations on rate schedule lines are always in the context of a single rate schedule and default time period. First one has to retrieve the rate schedule resource, for example using a GET operation. From that resource, get the URL of the rate schedule lines resource from the "rateScheduleLinesList". Use the entry with the "startDate" matching the default time period to be processed.
Only a collection resource exists for rate schedule lines, no singular resource. The collection resource supports POST, PUT and PATCH operations:
-
With POST, a number of rate schedule lines can be added to the rate schedule. Already existing lines for that schedule are not affected.
-
With PUT, a number of rate schedule lines can be sent in as the new set of lines for that resource. Existing lines not in the payload are deleted.
-
With PATCH, one can do individual operations on lines, without the need to send in the full set of lines.
| The PUT and PATCH operation use the technical id of the rate schedule line to match the payload with existing data. |
This is the message format for POST, PUT and PATCH:
{
"rateScheduleLineList": [{
"amount": {
"value": ""
},
"functionDynamicLogic": {
"id": ""
},
"<field name of schedule dimension with type value and datatype other than amount>": "",
"<field name of schedule dimension with type value and datatype amount>": {
"valueAmount" : {
"value": "",
"currency": ""
}
},
"<field name of schedule dimension with type range and datatype other than amount>": {
"valueFrom": "",
"valueTo": ""
},
"<field name of schedule dimension with type range and datatype amount>": {
"valueFromAmount": {
"value": "",
"currency": ""
},
"valueToAmount": {
"value": "",
"currency": ""
}
}
},
{
... other line(s)
}
]
}
POST payload
Example payload for inserting 2 rate schedule lines:
{
"rateScheduleLineList": [{
"amount": {
"value": 15
},
"age": {
"valueFrom": 18,
"valueTo": 99
},
"medicalCondition": "N"
}
{
"amount": {
"value": 20"
},
"age": {
"valueFrom": 18,
"valueTo": 99
},
"medicalCondition": "Y"
}
]
}
For details on how values in the request messages are handled, see Property Representation and Handling.
PUT payload
The payload for PUT is almost identical to the POST payload, the only difference is that the id property must be included for matching payload values to existing rate schedule lines.
| If the "id" property is omitted, the line is handled as a new one, instead of an update to an existing one. |
PATCH payload
The payload for PATCH is almost identical to the POST payload. The differences are that each line must include the "op" to identify the operation to be executed for that line and the id property for replacing or removing an existing line.
This payload will update the amount of a single line:
{
"rateScheduleLineList": [{
"id": 1,
"op": "replace",
"amount": {
"value": 16
}
}
]
}
| See HTTP API PATCH for more details about PATCH and "op". |