Your IP address could not be determined at this time.

Registration records and Reg-RWS

Table of Contents

The Big Picture

Before using or designing software to manage records within ARIN's database, it is important to understand ARIN's relational database, and how ARIN maintains records and interacts with customers.

IP Address and Autonomous System Number (ASN) Distribution

ARIN is one of five Regional Internet Registries (RIRs). RIRs are nonprofit corporations that administer and register IP address space and ASNs within defined regions. RIRs receive address space in large blocks from the Internet Assigned Numbers Authority (IANA), and allocate smaller address blocks to organizations within their regions. These organizations then assign IP addresses to consumers.

Allocations vs. Assignments

  • When ARIN registers a block of IP addresses to a customer planning to register pieces of that block to its own customers, this is known as an allocation.
  • When ARIN registers a block of IP addresses to an entity with no intention of splitting the block up among its customers, this is known as an assignment.

Note: Reallocations and reassignments may only be made from an allocation.

Note: ASNs are assigned individually by ARIN and may not be allocated.

When an ARIN customer registers a piece of their allocation to a customer of their own, this is known as a reallocation or reassignment, depending on whether their customer intends to register pieces of that block to customers of their own (reallocation) or if it is intended for internal use (reassignment).

Resource Requests

In order for ARIN to properly register Internet number resources to organizations within its region, those organizations submit a resource request, stating which type of resources they need, and how they intend to use them. ARIN requires that requests include utilization plans, so that ARIN can allocate them fairly among organizations as they continue to expand their networks and customer bases.

Keeping Track of Who Uses What

ARIN maintains a database that contains detailed records of which resources have been allocated and assigned, as well as which organizations and Points of Contact (POCs) are authoritative over those resource records.

ARIN's Database Records

Having trouble viewing the graphic below? Click here.

Reporting Reassignments

When an organization reassigns address space, they report reallocation/reassignment information to ARIN. This information is vital, as ARIN makes allocations based on an organization's utilization history, projected requirements, and other information. While initial allocations may be relatively small, subsequent allocation sizes are scaled based partially on growth shown via reallocation/reassignment information received by ARIN.

Simple vs. Detailed Reassignments

Simple reassignments are those where the customer does not need to maintain their own in-addr.arpa delegation, display their own POC information, or divide their address space further among their own customers. A detailed reassignment is one in which the customer does not need to further divide the space, but does need to maintain its own reverse name servers and/or display separate POC information.

How Resource Holders Manage Reallocations/Reassignments

ARIN customers have two options when it comes to reporting their reallocation/reassignment data. They may use Referral Whois (RWhois) or Shared Whois Project (SWIP).

  • RWhois: RWhois is an extension of the original Whois protocol and Service.  It focuses on the distribution of data representing networks and POCs, and uses the inherently hierarchical nature of these network objects (domain names, Internet Protocol (IP) networks, email addresses) to more accurately discover the requested information. RWhois allows organizations to advertise their reallocation/reassignment from an internal server, rather than actively sending it to ARIN. There are numerous requirements for using this sort of distribution server for reallocation/reassignment information, including 24/7 server functionality, response qualification, and continuity of data. For details, see Section 3.2 of ARIN's Number Resource Policy Manual (NRPM).
  • SWIP: SWIP is a process whereby ARIN customers report reallocation/reassignment data by sending it to ARIN either via email templates or using Representational State Transfer (REST).
    • Email Templates: ARIN customers have the option of sending a completed email form, or template, to hostmaster@arin.net to report reallocation/reassignment information. There are templates for creating, editing and removing subdelegations (allocations and assignments made from an allocated block of address space), both for IPv4 and IPv6 networks, which may be found on the reassignment reporting page. While email templates are an automatable way to report reassignment information and make the appropriate changes within ARIN's database, a more secure and direct method is Reg-RWS.
    • Reg-RWS: Registration RESTful Web Service (Reg-RWS) provides a secure and efficient method for interacting with ARIN's database. Reg-RWS is most handy for repetitive, mundane tasks done in high volume with no needed human communication, such as SWIP. In addition to being more secure than email templates, Reg-RWS allows for the retrieval of information about a record immediately before submitting changes to it. Reg-RWS also returns a predictable response that can be interpreted and reacted to by automation software. Organizations and people who spend a great deal of time sending new customer reallocation/reassignment data to ARIN's database will find significant value in a system built to help automate these transactions.

Before you get started...

Create an ARIN Online Account

Your first step is to create an ARIN Online account. Every individual who manages organization or resource records should create an ARIN Online account using an individual email address. Unlike POC records, ARIN Online accounts cannot use role email addresses, nor should they be shared, or transferred to another person. ARIN Online accounts are portable, and registered users can continue to use their accounts when they move or change jobs because accounts can be unlinked from POC, organization and resource records. In order to create an ARIN Online account, just visit ARIN's homepage (www.arin.net) and click “new user?” above the login boxes on the left side of the page.

Create an API Key

After creating your account and logging in to ARIN Online, a user must create an API Key. An API Key provides a means of secure communication with ARIN, and is required to SWIP using email templates or Reg-RWS. API Keys are created within ARIN Online by logging in and selecting WEB ACCOUNT on the left-hand side, and scrolling down to “API Key Management.”

Create a POC and Give it Authority

Before reporting reallocation/reassignment data, the user's ARIN Online account must have the authority to do so. ARIN's Reg-RWS and email template system will not process any modifications to a database record unless the user has an ARIN Online account linked to a POC with proper authority over that record. For more information on creating POCs, click here.

Once a user creates or finds the right POC in ARIN's database, that POC must be linked to the user's ARIN Online account. This may be done while logged into ARIN Online by clicking POC RECORDS on the left and selecting “link to it” within the top section of the page. This allows the user to select a POC record matching your account information and link it to their ARIN Online account. For more information on linking an ARIN Online account to a POC, click here.

Last but not least, you will need to create or find the appropriate ORG to add your POC to it as an Admin and/or Tech POC. This allows your POC (and your ARIN Online account) to make changes to ARIN's database regarding your ORG and any resources attached to it. For information regarding ORG creation, click here.

Using Reg-RWS to Register Reallocations and Reassignments

            Note: This section applies only to Reg-RWS users. Click here for SWIP Email Templates/Instructions.

Check to be sure you have:

Once the above requirements have been met, you are ready!

ARIN Online users can use Reg-RWS to retrieve and modify records within ARIN's database by sending URLs and xml payloads in an automatable, computer-friendly manner using modern application interfaces that provide strong authentication. ARIN Online users can interact with ORGs, POCs, NETs, reallocation/reassignment information, Delegations, and Tickets using Reg-RWS.

Anatomy of a Reg-RWS URL

The URL that is used when interacting with ARIN through Reg-RWS will specify three key things:

  • The address of the database being interacted with
  • The object being interacted with
  • The API Key associated with the user's ARIN Online account

For example, if looking for information on a certain POC record, use:

https://reg.arin.net/rest/poc/POCHANDLE?apikey=APIKEY

The address is a fixed location that defines the ARIN database and allows you to retrieve information from it. For Reg-RWS, the address is https://reg.arin.net.

Additionally, the user must specify the record they are attempting to view, change or delete by including the handle of the database record in the URL. If creating a record, a handle is not necessary.

Note: If a sample URL contains an all-caps string such as POCHANDLE, that string must be substituted with the appropriate handle/object identifier before submitting.

The final piece is an API Key. As stated above, API Keys are created in ARIN Online once an account has been created. For more information on creating an ARIN Online account, see About ARIN Online. Remember that before altering any records in ARIN's database, the user's ARIN Online account must be linked to a POC with authority over those records. A user may request to be linked to authoritative POCs through ARIN Online after an account has been created.

Note that the "apikey=" variable name in the URL must be lowercase, or an error will occur. The API Key itself must be uppercase. For example:

https://reg.arin.net/rest/poc/DUDE1-ARIN?apikey=API-1234-1234-1234-1234 HTTP/1.1

Methods and Payloads

A method is a type of interaction with ARIN's database records, or “call,” within Reg-RWS. When sending URLs through Reg-RWS, users must also specify the method of interaction their specific call uses.

  • GET retrieves information about a record
  • POST creates a new record
  • PUT modifies an existing record  
  • DELETE deletes a record

When using methods that alter database records without deleting them (PUT and POST), Reg-RWS will require more information than the URL provides. For example, if the user wishes to create or change contact information for a POC or ORG, Reg-RWS will require them to provide that information in a computer-friendly manner. To accomplish this, the user must send formatted xml layouts known as payloads. These payloads contain details about the record being created or modified, including organization information, POC information, IP address ranges, customer data, etc. To ensure that your payload is current, perform a GET before performing a PUT or POST with a given record. 

ARIN provides methods and payloads pages for Reg-RWS users. The Methods Page describes each database interaction, the appropriate method and URL structure, and which payloads will be sent and returned. The Payloads Page details each payload structure, provides examples of completed payloads and explains common error codes returned by Reg-RWS when it receives information it cannot understand or process correctly.

Methods

Within the Methods Page, there will be entries for each database interaction. Below is the “GET POC” method. Note that the URL segment used in the Methods Page is to be preceded by https://reg.arin.net. In this example, the user is retrieving information about a POC. Therefore, the URL must contain the appropriate POC handle and the user's API Key. There is no payload being sent to retrieve this information, so the Content field does not specify a payload. The Returns field specifies the payload that the user will see returned from Reg-RWS upon sending a correct URL using the correct method.

Description: Macintosh HD:Users:shopkins:Desktop:Screen shot 2012-03-21 at 7.32.22 AM.png

Payloads

Each entry on the Payloads Page explains a particular xml payload and provides an example of said payload already completed using sample information. The payload entry also shows which fields may not be modified or are generated by Reg-RWS automatically, as illustrated below:

Description: Macintosh HD:Users:shopkins:Desktop:Screen shot 2012-04-13 at 4.17.15 PM.png

The next piece of each payload entry is the payload itself shown with all fields empty. The user may then copy the code and fill it out within a REST software client before sending it to ARIN's Reg-RWS. A segment of the POC payload is pictured below:

Description: Macintosh HD:Users:shopkins:Desktop:Screen shot 2012-03-21 at 7.33.49 AM.png

Finally, the entry provides an example of a completed payload to help the user fill it out correctly. Below is a segment of the example POC payload.

Description: Macintosh HD:Users:shopkins:Desktop:Screen shot 2012-03-21 at 7.34.10 AM.png

Using Reg-RWS to Request Reports

Reg-RWS can also be used to request a number of reports available through ARIN Online.  Reassignments and Associations reports are available to all registered ARIN Online users.  However before you can request a WhoWas report, you must request WhoWas access and accept the WhoWas Terms of Use.

Before you request a report using Reg-RWS, check to be sure you have:

Once the above requirements have been met, you are ready!

If you haven't used Reg-RWS before, please refer to the reassignments and reallocations section of this page for a detailed explanation of Reg-RWS urls and methods and payloads.  If you are familiar with the system, read on for links to the methods information for each of the available reports.

Available Reports

Frequently Asked Questions about Reg-RWS

How Does Reg-RWS Benefit Me?

REST is not intended for human consumption. It can be difficult to read, write, or understand, and is less than forgiving if you make an error. It is designed, rather, for computers and automation software. Computers can easily interact with REST for four main reasons:

  • Predictable input and response mechanisms
  • Discrete set of responses
  • Instant responses
  • Secure, authenticated communication

When working with Reg-RWS, you can program the computer so it knows what to say, when to say it, what the response will be, and how to interpret the response it receives, all with little to no additional human interference. What's more, these instant transactions within ARIN's database are secure and authenticated using a unique API Key.

When Do I Benefit most from Reg-RWS?

Reg-RWS is great for many activities within ARIN's database. It is secure and efficient for repetitive, mundane tasks done in high volume with no needed human communication. The most prominent example of this type of activity is SWIP: the process through which Internet Service Providers submit customer IP address space reassignment information to Whois.

Why is SWIP Such a Good Fit for Reg-RWS?

Put simply, Reg-RWS provides the instant, secure, predictable format for communicating with ARIN's database that is ideally suited for SWIPs. Organizations and people who spend a great deal of time sending new customer reassignment data to ARIN's database will find significant value in a system built to help automate these transactions.

How is Reg-RWS Better than Using Email Templates?

While email templates are an automatable way to perform actions within ARIN's database, Reg-RWS is a more secure, more direct transaction. Additionally, Reg-RWS allows for the retrieval of information about a record immediately before submitting changes to it. Reg-RWS also returns a predictable response that can be interpreted and reacted to by automation software.

How Can I Test Reg-RWS Interactions Without Affecting My Production Data?

ARIN has implemented an Operational Test and Evaluation environment (OT&E) containing a copy of production-like data, refreshed monthly, that allows developers to experiment with ARIN interactions without affecting production data. For more information, see the OT&E page.

Troubleshooting

Errors may happen for a wide variety of reasons. When Reg-RWS notifies you of an error with your URL/payload, it does so by returning an error code, along with a "body" containing an Error Payload which will categorize the issue or issues contained within your submitted URL/payload.

If a call does not perform properly, there are several reasons why it may have failed. Be sure that:

  • You have not filled in any immutable or system-generated fields

Note: When creating an object, all fields not automatically generated must be filled out

  • You have not included any fields which do not belong in your payload
  • You have not omitted a required field.
  • Your payload and URL are free of typos
  • Your URL, including API Key, is in the correct case (upper/lowercase)
  • You selected the appropriate payload to send, and method with which to send it.
  • Your API Key is valid and linked to an ARIN Online account with the authority to alter or delete any records you are attempting to interact with.
  • Your URL contains the proper record identifiers (Handle) and other required information per the method you are using.
  • Within your REST client, you have:
    • specified "US-ASCII or UTF-8" as your character set
    • specified the MIME type as “application/xml”

If the above list does not assist you in correcting the issue, please feel free to subscribe and submit to ARIN's tech-discuss mailing list, or by using the Ask ARIN feature within ARIN Online.

Vendors

We are only aware of one vendor at this time who offers an IP Address Management (IPAM) product that is helpful for interfacing with ARIN's Reg-RWS. If you are aware of other products, email info@arin.net with details and we can add them here.

ARIN also offers a set of  open source command-line scripts, written in Ruby, that utilize both the Whois-RWS service and the Reg-RWS service (formerly ARINr).