SUPPORT STORE CONTACT SIGN IN
Overview
System
Network
Services
Identities
Policies
Billing
Archives
Instruments
Installation
Lab Manual
Portal Customization
RESTful API
Miscellaneous
View as one page

Create

Creating a record is simply a matter of sending an HTTP POST to the appropriate URL. Consider the simple example of creating a WAN Target. To accomplish this an HTTP POST request would be sent to a URL of the form:

https://rxg.dns/admin/scaffolds/wan_targets/create.xml?api_key=8f8eab...868c

with a header containing:

Content-Type: application/xml

and a payload of the form:

<?xml version="1.0"?>
<record>
  <name>Desired New Name</name>
  <targets>1.2.3.4</targets>
</record>

This entire process may be accomplished by using the cURLcommand line utility. Below is an example command line that demonstrates the use of cURL to execute a create through the RESTful API.

curl -i -X POST -H 'Content-Type: application/xml'
  -d '<?xml version="1.0"?><record><name>Desired New Name</name>
      <targets>1.2.3.4</targets></record>'
  https://rxg.dns/admin/scaffolds/wan_targets/create.xml?api_key=486...a5a

The RESTful API endpoint will respond with a HTTP/1.1 201 Createdthat has a Location header containing the URL to retrieve the record upon successful creation. The content of the response is a copy of the created record.

HTTP/1.1 201 Created
Location: https://rxg.dns/admin/scaffolds/wan_targets/show/5.xml?api_key=486...876a
Content-Type: application/xml; charset=utf-8
X-UA-Compatible: IE=Edge
ETag: "40c13943442b4dd5646d264fdb738909"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _rxg_console_session=BAh7Ck...ea6e5; path=/; HttpOnly
X-Request-Id: 43eda966fa00bd1347f48583f37e5392
X-Runtime: 0.439131
Content-Length: 155
Connection: keep-alive
Server: thin 1.3.1 codename Triple Espresso

<?xml version="1.0" encoding="UTF-8"?>
<wan-target>
<name>New Target Name A</name>
<note nil="true"></note>
<targets>2.2.3.4</targets>
</wan-target>

If an error occurs and the record is not created the response will be an HTTP error status (usually HTTP/1.1 422) and the content will contain the error messages. For example, if the same request is run twice, then the response would take the form:

HTTP/1.1 422
Content-Type: application/xml; charset=utf-8
Cache-Control: no-cache
Date: Mon, 28 May 2012 17:35:23 GMT
X-UA-Compatible: IE=Edge,chrome=1
Set-Cookie: _rxg_console_session=BAh7C...098b1; path=/; HttpOnly
X-Request-Id: 63bb95530945b6be578eaf4485d7a337
X-Runtime: 1.800010
X-Rack-Cache: invalidate, pass
Connection: close
Server: thin 1.3.1 codename Triple Espresso

<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>Name has already been taken</error>
<error>Targets has already been taken</error>
</errors>

There are requirements that need to be met when creating records. Required fields are marked in bold in the web administrative console.

Hitting the appropriate URL without sending the required input will result in a dump of error messages that describe the requirements. For example, using cURL to send the following request:

curl -i -X POST -H 'Content-Type: application/xml'
  -d '<?xml version="1.0"?><record><login>restfulapitest</login></record>'
  https://rxg.dns/admin/scaffolds/accounts/create.xml?api_key=WR5..KLw

Results in the the following response.

HTTP/1.1 422
Content-Type: application/xml; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
Cache-Control: no-cache
Set-Cookie: _rxg_console_session=BAh...8b1; path=/; HttpOnly
X-Request-Id: 63bb95530945b6be578eaf4485d7a337
X-Runtime: 1.800010
Date: Mon, 28 May 2012 14:32:18 GMT
X-Rack-Cache: invalidate, pass
Connection: close
Server: thin 1.3.1 codename Triple Espresso

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Email can't be blank</error>
  <error>Email is too short (minimum is 3 characters)</error>
  <error>Email is invalid</error>
  <error>Password can't be blank</error>
  <error>Password is too short (minimum is 1 characters)</error>
  <error>Password confirmation can't be blank</error>
  <error>First name can't be blank</error>
  <error>First name is too short (minimum is 2 characters)</error>
  <error>Last name can't be blank</error>
  <error>Last name is too short (minimum is 2 characters)</error>
  <error>Time must be configured unless unlimited is checked</error>
  <error>Upload quota must be configured unless unlimited is checked</error>
  <error>Download quota must be configured unless unlimited is checked</error>
  <error>Expiration must be configured unless unlimited is checked</error>
</errors>

The reported errors may be used to construct a correct request to send to the RESTful API endpoint such as the following example:

curl -i -X POST -H 'Content-Type: application/xml' \
 -d '<?xml version="1.0"?><record><login>restfulapitest</login>
     <email>[email protected]</email><password>1234567890</password>
     <password_confirmation>1234567890</password_confirmation>
     <first_name>api</first_name><last_name>test</last_name>
     <unlimited-usage-mb-down>1</unlimited-usage-mb-down>
     <unlimited-usage-mb-up>1</unlimited-usage-mb-up>
     <unlimited-usage-minutes>1</unlimited-usage-minutes>
     <no-usage-expiration>1</no-usage-expiration></record>'
 https://rxg.dns/admin/scaffolds/accounts/create.xml?api_key=WR5...KLw

Which results in a response of:

HTTP/1.1 201 Created
Location: https://rxg.dns/admin/scaffolds/accounts/show/36.xml?api_key=WR5...KLw
Content-Type: application/xml; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "e71...4c7"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _rxg_console_session=BAh...dc6; path=/; HttpOnly
X-Request-Id: 111b836e66f0883a4900d37a8c0ff42e
X-Runtime: 0.040524
Date: Mon, 28 May 2012 18:55:57 GMT
X-Rack-Cache: invalidate, pass
Connection: close
Server: thin 1.3.1 codename Triple Espresso

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <address1 nil="true"></address1>
  <address2 nil="true"></address2>
  <automatic-login type="boolean" nil="true"></automatic-login>
  <bill-at type="datetime" nil="true"></bill-at>
  <charge-attempted-at type="datetime" nil="true"></charge-attempted-at>
  <city nil="true"></city>
  <company nil="true"></company>
  <country nil="true"></country>
  <created-at type="datetime">2012-05-28T14:55:57-04:00</created-at>
  <created-by>apikeytest</created-by>
  <crypted-password>y/j0nSYiWmwho4X8jj0symrxccU=</crypted-password>
  <email>[email protected]</email>
  <first-name>api</first-name>
  <id type="integer">36</id>
  <last-name>test</last-name>
  <lock-mac type="boolean" nil="true"></lock-mac>
  <lock-version type="integer">0</lock-version>
  <logged-in-at type="datetime" nil="true"></logged-in-at>
  <login>restfulapitest</login>
  <mb-down type="integer" nil="true"></mb-down>
  <mb-up type="integer" nil="true"></mb-up>
  <no-usage-expiration type="boolean">true</no-usage-expiration>
  <note nil="true"></note>
  <phone nil="true"></phone>
  <pkts-down type="integer" nil="true"></pkts-down>
  <pkts-up type="integer" nil="true"></pkts-up>
  <region nil="true"></region>
  <relative-usage-lifetime type="integer" nil="true"></relative-usage-lifetime>
  <salt>dcfae2f069cb8167972225ba7c33d6ac5642fd2a</salt>
  <state>active</state>
  <unlimited-usage-mb-down type="boolean">true</unlimited-usage-mb-down>
  <unlimited-usage-mb-up type="boolean">true</unlimited-usage-mb-up>
  <unlimited-usage-minutes type="boolean">true</unlimited-usage-minutes>
  <updated-at type="datetime">2012-05-28T14:55:57-04:00</updated-at>
  <updated-by nil="true"></updated-by>
  <usage-expiration type="datetime" nil="true"></usage-expiration>
  <usage-mb-down type="integer" nil="true"></usage-mb-down>
  <usage-mb-up type="integer" nil="true"></usage-mb-up>
  <usage-minutes type="integer" nil="true"></usage-minutes>
  <usage-plan-id type="integer" nil="true"></usage-plan-id>
  <zip nil="true"></zip>
</account>

Accounts must be assigned policy in order for enforcement to take effect. Policies are associated to Accounts through Account Groups. Associating Accounts with Account Groups is usually accomplished by setting either the do_apply_usage_planor the do_bill_and_apply_usage_plan virtual attribute. For example:

curl -i -X POST -H 'Content-Type: application/xml'
 -d '<?xml version="1.0"?><record><login>restfulapitest</login>
     <email>[email protected]</email><password>1234567890</password>
     <password_confirmation>1234567890</password_confirmation>
     <first_name>api</first_name><last_name>test</last_name>
     <usage-plan>3</usage-plan>
     <do_apply_usage_plan>1</do_apply_usage_plan></record>'
 https://rxg.dns/admin/scaffolds/accounts/create.xml?api_key=w1f...kkQ

Notice that the usage time, usage expiration and upload/download usages are not specified because they are defined by the plan. Also notice that the usage-plan attribute is used to specify the desired Usage Plan by ID. The Usage Plan ID may be acquired by using the list action for the usage-plansscaffold. Note that the value of do_apply_usage_plan or the do_bill_and_apply_usage_plan virtual attributes should always be 1. If you set the value of thedo_apply_usage_plan or the do_bill_and_apply_usage_planto anything other than 1 then the system will not execute the command at all. The following is an example of the response to a successful Account record creation with Usage Plan specification and application as shown above.

HTTP/1.1 201 Created
Location: https://rxg.dns/admin/scaffolds/accounts/show/24.xml?api_key=LjU...kkQ
Content-Type: application/xml; charset=utf-8
X-UA-Compatible: IE=Edge,chrome=1
ETag: "4dcf...2322"
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: _rxg_console_session=BAh...03f; path=/; HttpOnly
X-Request-Id: 5c4...841
X-Runtime: 0.039446
Date: Fri, 22 Jun 2012 21:49:40 GMT
X-Rack-Cache: invalidate, pass
Connection: close
Server: thin 1.3.1 codename Triple Espresso

<?xml version="1.0" encoding="UTF-8"?>
<account>
  <address1 nil="true"></address1>
  <address2 nil="true"></address2>
  <automatic-login type="boolean" nil="true"></automatic-login>
  <bill-at type="datetime" nil="true"></bill-at>
  <charge-attempted-at type="datetime" nil="true"></charge-attempted-at>
  <city nil="true"></city>
  <company nil="true"></company>
  <country nil="true"></country>
  <created-at type="datetime">2012-06-22T16:49:40-05:00</created-at>
  <created-by>useronly</created-by>
  <crypted-password>pMId/QzJ.....NMc1vjObnk=</crypted-password>
  <email>[email protected]</email>
  <first-name>api</first-name>
  <id type="integer">24</id>
  <last-name>test</last-name>
  <lock-mac type="boolean" nil="true"></lock-mac>
  <lock-version type="integer">0</lock-version>
  <logged-in-at type="datetime" nil="true"></logged-in-at>
  <login>restfulapitest</login>
  <mb-down type="integer" nil="true"></mb-down>
  <mb-up type="integer" nil="true"></mb-up>
  <no-usage-expiration type="boolean" nil="true"></no-usage-expiration>
  <note nil="true"></note>
  <phone nil="true"></phone>
  <pkts-down type="integer" nil="true"></pkts-down>
  <pkts-up type="integer" nil="true"></pkts-up>
  <region nil="true"></region>
  <relative-usage-lifetime type="integer" nil="true"></relative-usage-lifetime>
  <salt>37ddbeec583e.....04d94ab939f5</salt>
  <state>active</state>
  <unlimited-usage-mb-down type="boolean">true</unlimited-usage-mb-down>
  <unlimited-usage-mb-up type="boolean">true</unlimited-usage-mb-up>
  <unlimited-usage-minutes type="boolean">true</unlimited-usage-minutes>
  <updated-at type="datetime">2012-06-22T16:49:40-05:00</updated-at>
  <updated-by nil="true"></updated-by>
  <usage-expiration type="datetime">2012-07-22T16:49:40-05:00</usage-expiration>
  <usage-mb-down type="integer" nil="true"></usage-mb-down>
  <usage-mb-up type="integer" nil="true"></usage-mb-up>
  <usage-minutes type="integer" nil="true"></usage-minutes>
  <usage-plan-id type="integer">3</usage-plan-id>
  <zip nil="true"></zip>
</account>

About

RG Nets is the premium provider of gateways and centralized-authentication appliances designed to manage, provision, and protect revenue-generating networks. Our mission is to create tools that are so good, we would use our own money to buy them.
316 California Ave.
Suite 331
Reno, NV 89509
+1 (408) 441 0100
[email protected]

Company Links

Copyright 2025 RG Nets, Inc.
v2025.08
Cookies help us deliver our services. By using our services, you agree to our use of cookies.