Reg-RWS Basics: Learn to Automate Management of ARIN Records with API

By Jon Worley – Senior Technology Architect

ARIN’s Registration RESTful Service, or Reg-RWS, is a secure and efficient method for interacting with ARIN’s database and managing your registration records. It can be used to automate tasks such as creating a recipient customer, submitting reassignment or reallocation information, modifying nets, and more.

As part of our preparations for the 3 June 2024 retirement of SWIP email templates for reporting reallocations and reassignments, we hosted a webinar to explain the benefits Reg-RWS can bring to customers’ organizations. With that training now available in our library of on-demand instructional webinars, you have 24/7 access to learning about creating and managing API keys and the four calls you will need most — simple reassignments that do not require any action by your customers.

Read on for an overview of the information or watch the one-hour webinar hosted by our Senior Technology Architect Jon Worley for the full details and demonstrations. We encourage organizations who utilize email templates for reporting information to ARIN to watch so you can be prepared for the retirement of email templates in less than two months.

API Keys and Management

An API key is a string of 32 hexidecimal characters in the form API-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX that functions like your username and password and is included in the URL when you ask ARIN to create a customer record or reassignment. It has the same authority and privileges you would when logged in to your ARIN Online account. Unlike using email templates, the API is an effective way to deliver structured information without the risk of formatting errors and misinterpretation of characters.

When you create an API key by following the steps in ARIN Online pictured below, make sure to store it somewhere safe. For security purposes, after your key is created and displayed one time, the full key will never again be displayed — not even to ARIN staff, so we can’t retrieve it for you.

Managing your API key comes down to choosing when to deactivate it and create a new one. You can do this on a schedule or wait until you believe the key may be compromised or you no longer know the full key. The current management actions available also include the option to associate an email, but this is not recommended and will soon no longer be possible due to the pending deactivation of email templates.

Creating a Recipient Customer

This is step one in the two-step process to report a reassignment. If you’ve been using email templates to do that, you can think of the two-step process as translating your email into two calls: 1) creating a customer record; and 2) creating a reassignment record.

The Create Recipient Customer call generates a Customer Handle using the details in the Customer Payload you provide, and the handle in your URL specifying the parent NET from which this Org will be receiving a simple reassignment. The call will return a payload containing information about this newly created customer. To avoid receiving an error, be sure your API key is linked to a Point of Contact who is either the Admin or Tech Point of Contact for the Org holding the parent NET or the Tech Point of Contact for the parent NET itself.

• RESTful Method: POST
• URL: https://reg.arin.net/rest/net/PARENTNETHANDLE/customer?apikey=APIKEY
• Content: Customer Payload
• Returns: Customer Payload

Creating a Customer Reassignment

Step two in the reassignment reporting process is to issue a Reassign NET call. This call performs a reassignment from the NET specified in your URL using the recipient information contained in the NET Payload you provide. Reassignments are given to an Org or customer for its own use and may not be reallocated or reassigned further. Two types of reassignments can take place — simple and detailed — but the Reg-RWS webinar only covers simple reassignments.

• RESTful Method: PUT
• URL: https://reg.arin.net/rest/net/PARENTNETHANDLE/reassign?apikey=APIKEY
• Content: NET Payload
• Returns: Ticketed Request Payload

Managing a Customer Reassignment

Up to this point you have used the Parent Net Handle to create a customer record and report the reassignment. When it comes to managing a reassignment after that, you will act on the Net Handle. The Modify NET call will modify the details of the NET specified in your URL. When making this call, attach a NET Payload containing the details of the NET you intend to modify. To ensure accuracy, use Get NET to get the most current information before making changes. This call returns a payload containing that NET’s information as it exists after modification.

• Method: PUT
• URL: https://reg.arin.net/rest/net/NETHANDLE?apikey=APIKEY
• Content: NET Payload
• Returns: NET Payload

Removing a Customer Reassignment

Now we reach the end of the line, when a customer no longer needs their connection with you. As a matter of database hygiene, it is important to remove the relevant record. We have a big database, and the less irrelevant, unused information it contains, the better. Plus, old stale reassignment records can be used by bad actors.

The Remove NET call will delete the details of the NET specified in your URL. You do not need to attach a NET Payload, but it will work if you include one. This call returns a payload containing that NET’s information as it existed before deletion.

• Method: DELETE
• URL: https://reg.arin.net/rest/net/NETHANDLE?apikey=APIKEY
• Content: None
• Returns: Ticketed Request Payload

Also note that we don’t automatically delete the customer handle once you delete the reassignment, so it’s not a bad idea to delete the customer handle as well.

SWIP Email Template Retirement

Effective 3 June 2024, ARIN will be retiring SWIP email templates for reporting reallocations and reassignments as described in the Community Consultation conducted in November 2023. We will be working directly with the less than 75 customers impacted by the change to guide them through this transition to Reg-RWS, and we have completed the following major improvements to ease the impact prior to retiring the template processor:

• Published an open-source template processor through GitHub on 31 October 2023 that can convert email templates to REST calls that can be received by Reg-RWS. This template processor is a self-contained product that customers may run within their network to process templates. This is meant as a stopgap solution and, once released, will not be maintained or supported. If customers wish to use this product beyond its initial release, they will be able to fork the repository and maintain it as their needs require.
• Deployed updates to ARIN Online on 7 August 2023 to provide feature parity with the existing template processor for reassignments.

As 3 June approaches, we will continue to engage with customers who use email templates to educate them on alternative options and assist with their direct transition to Reg-RWS.

After 3 June 2024, ARIN will not accept or respond to email templates.

If you have questions about this transition or need assistance using Reg-RWS, you can contact us by:

• submitting an Ask ARIN ticket or chat with us using your ARIN Online account, or
• calling the Registration Services Help Desk at +1.703.227.0660 (Monday-Friday, 7:00 AM-7:00 PM ET).

If You Want to Explore Other Topics

Need training on another topic? We have more on-demand webinars available for you to access today! Check out offerings on IPv6 address planning, using ARIN’s IRR-online or our RESTful API for IRR, and ARIN’s Policy Development Process — all led by experts within our organization.

Find all available on-demand webinars in our Training & Education resources.

Thank you to all webinar participants who have attended live and watched on-demand; we hope you have found them valuable. If you have an idea for a topic of a future webinar, email [email protected] to share it with us!

Recent blogs categorized under: Training

• RPKI Learning Just a Click Away
• ARIN Leadership Development Series On-Demand Videos Now Available
• Using ARIN's RESTful API for IRR
• ROA, ROA, ROA Your Network with ARIN’s Upcoming RPKI Webinar