Public API Draft (for Members)

(Proposed 2018. Withdrawn pending re-specification 2021).

Overview

This draft document describes the higher-level functionalities of the proposed APNIC registry APIs.  It is not meant to be a technical reference documentation rather, it is intended as a guide to prompt feedback about its scope and design.

It was published in 2018. Due to other commitments, APNIC has been unable to proceed to deployment.

The following text remains to help explain APNIC’s intent in any future API design.

If you have any questions or comments, or if you wish to register interest in a future Public API, please email feedback@apnic.net. At this time, APNIC does not expose a Public API for general use.

Introduction

Members have often indicated that working with Whois is difficult.  Although APNIC currently provides various APIs for Member use, these tend to be awkward to use (Whois updates via email) or for niche purposes (RPKI provisioning protocol for self-hosted RPKI engines).

The APIs attempt to alleviate this by abstracting away from Whois where possible, and making required Whois changes in the background.

The registry APIs described in this document cover all the standard registry functions Members use on a day-to-day basis: customer assignments, RDNS, and route registration, as well as direct Whois access for more experienced users.  These will allow Members to streamline their processes and integrate with APNIC more effectively.

Technology

The APNIC registry APIs will be implemented as RESTful HTTP services.  More specifically, they will be:

• resource-based;
• stateless: no client context or session control will be stored on the server; and
• self-describing: all functionality available via the API will be determinable by navigation from the API entry page, including in-band resource schemas and links for creating new resources.

Each resource will document the HTTP methods that it supports. In general, GET is used for retrieval, POST for creation, PUT for updates and for creation with specific resource identifiers, and DELETE for deletion.

HTTP response codes will be used to indicate application results.  Information returned in the response body will be either a resource, as per the following documentation, or a standard ‘error’ response containing further structured detail about what went wrong.

To avoid confusion between Internet resources and REST resources, the abbreviation ‘INR’ (for ‘InterNet Resource’) will be used for the former throughout.

Data format

JSON will be the principal data format for the APNIC API.

Authentication

Requests to the APNIC API will be authenticated with an API key that can be generated via (MyAPNIC/SSO).  The API key will be tied to the generating user account and will have the permissions specified when generating the key.  Because keys are tied to user accounts, it is possible for an API to have access to multiple Member accounts if the user account has permissions for multiple Member accounts.

It will be possible to generate multiple keys for a single user account, for use in different contexts, and to revoke them individually.

General principles

Each resource will contain a ‘self’ link, being a URL that points to the resource.

On creation, all resources will be assigned an opaque, internally-generated identifier.  This will be stored against the ‘id’ field of the resource.

Nested resources will generally not include any details other than an ID and a ‘self’ link.  It will be possible to retrieve details for all nested resources by passing an additional flag when making the request.

Resource hierarchies will be avoided where possible.

Each resource type will have an associated ‘list’ endpoint, allowing for all relevant instances of that resource to be located.  These endpoints will support pagination, filtering, and ordering.  They will generally not allow for retrieving all resources via a single API call.

It will not be possible to DELETE a resource if other resources are still dependent on it.

The API will employ an asynchronous mode of operation for requests that may involve delays, by returning a URL that can be used to check on the status of the request, rather than waiting for those backend actions to be completed.

Data model

Each of the resource types that are used within the system are described in this section.

Entity

An ‘entity’ is a contact point, and may represent a specific person or an organizational function.  Entities may be associated with a Member’s organization directly, or with one of its customers, or with some other third party.

Entities are used throughout the API: for example, when a reverse DNS delegation is created, it is necessary to include references to the entities that will handle administrative and technical inquiries about that delegation.

An entity contains the following details:

• Name
• External ID
• vCard
• Roles
• Entities

Most of an entity’s details are contained within its vCard.  English-language details must be provided when creating an entity; however, details in other languages may also be provided.

An entity may carry out one of three roles with respect to other resources in the system: ‘administrative’, ‘technical’, or ‘abuse’.  An entity’s roles may be specified at the entity level, or the customer level, or the INR level, with each later level taking precedence over the former.

Where an entity represents an organizational function, the specific people that fulfil that function may be listed in the optional ‘Entities’ element.

The entity resource will support the GET, POST, PUT, and DELETE methods.

Customer

A ‘customer’ is a person or organization to whom a Member assigns INRs.  While some Members assign INRs to people or organizations who are not their customers, this is comparatively rare, hence the use of this term.

A customer contains the following details:

• Name
• External ID
• Economy
• Entities

The customer resource will support the GET, POST, PUT, and DELETE methods.

Customer Assignment

A ‘customer assignment’ represents a delegation of INRs from a Member account to a Member’s customer.  It contains the following details:

• INR range
• Customer
• Network name
• Description

On creating a ‘customer assignment’, it will be possible to specify a resource prefix length in lieu of a range.  In that case, the resource range actually used for the assignment will be the next-available range of the specified length that belongs to the Member.

Once created, only the network name and description of an assignment may be updated.

If a customer assignment is deleted, the resources will again become available. If a customer assignment is attempted for resources that are already in use (whether partially or fully), an error will be returned.

The customer assignment resource will support the GET, POST, PUT, and DELETE methods, subject to the previous qualifications.

Delegation

A ‘delegation’ represents a specific delegation of INRs from APNIC to a Member account.  It contains the following details:

• INR range
• INR type (allocation, assignment)
• Date of delegation

The delegation resource will support the GET method.

Aggregate Delegation

An ‘aggregate delegation’ represents an aggregated set of INRs that have been delegated by APNIC to a Member account.  The difference between a delegation and an aggregate delegation is that the latter can cover multiple delegation events if the relevant resources are aggregateable.  For example, if a Member received 192.0.2.0/24 on one day, and 192.0.3.0/24 on another day, this would be represented as a single aggregate delegation (192.0.2.0/23), but two delegations.

It contains the following details:

• INR range
• INR type (allocation, assignment)

The Aggregate Delegation resource will support the GET method.

Resource Request

A ‘resource request’ represents a request made by a Member to APNIC for further INRs.  It contains the following details:

• INR type (IPv4, IPv6, ASN)
• INR delegation type (allocation, assignment)
• Request-specific details
• Status
• Ticket

The request-specific details are omitted here for brevity. For example, an IPv4 assignment request may be to support multihoming, or for the operation of an IXP, or for the provision of critical infrastructure, with each request type having different parameters and constraints.

This resource’s name is an exception to the use of the term ‘INR’ in this document.

The resource request resource will support the GET and POST methods.

Resource Transfer

A ‘resource transfer’ represents a request made by a Member to APNIC to transfer certain resources to another APNIC Member.  It contains the following details:

• INR ranges
• Transfer type (normal, M&A)
• Source account
• Destination account
• Reason for transfer
• Whois action (keep/delete)
• Status
• Ticket

On creating a resource transfer, the source account, status, and ticket are omitted.

This resource’s name is an exception to the use of the term ‘INR’ in this document.

The resource transfer resource will support the GET and POST methods.

The endpoint that lists the resource transfers for a specific Member account will include both inbound and outbound transfers, hence the inclusion of both the source and the destination account fields within this resource.

Resource Return

A ‘resource return’ represents a request made by a Member to return resources to APNIC.  It contains the following details:

• INR ranges
• Status
• Ticket

On creating a resource return, the status and ticket are omitted.

This resource’s name is an exception to the use of the term ‘INR’ in this document.

The resource return resource will support the GET and POST methods.

Although Members may return resources to APNIC as of right, this is handled as a request to be reviewed by APNIC staff due to the potential consequences if a return has been submitted in error.

Reverse DNS Delegation

A ‘reverse DNS delegation’ represents the delegation of reverse DNS from APNIC to a set of specified nameservers.  It contains the following fields:

• INR range
• Nameservers
• Entities

Arbitrary INR ranges may be used: the system will create the appropriate set of domain records in the background.

The reverse DNS delegation resource will support the GET, POST, PUT, and DELETE methods.

Route

A ‘route’ resource represents a registration of routing intent, i.e. that an announcement of a specific set of address ranges may/will be made from a specific AS number.  It contains the following fields:

• INR range
• Enabled routes
• Origin AS
• Most specific announcement
• ROA status
• Whois status

On creating a route, both the enabled routes and the most specific announcement fields are optional. The former is used to indicate that only specific address ranges within the INR range may be announced.  The latter is used to indicate that any announcement up to a given prefix length that falls within the INR range should be considered valid.  These fields are mutually exclusive.

Routes will be structured so that it will be possible for additional routing intent systems to be supported easily in the future.

The route resource will support the GET, POST, PUT, and DELETE methods.

Maintainer

At various points, the APIs have to interact with Whois in the background. This may include the creation of new maintainers for entities or customers, among other things.  In order to allow Members who need to interact with Whois directly more control over their objects, it will be possible to list the maintainers associated with the user’s account.  Where the API has to carry out actions against Whois, the authentication details from these maintainers will be used, if required.

Apart from the ID that is generated for all objects, a maintainer contains all of the Whois details, copied directly from the maintainer object in Whois.

The maintainer resource will only support the GET method.

Ticket

A ‘ticket’ resource represents a communication with APNIC staff.  It contains the following fields:

• Subject
• Queue
• Status
• Attachments

Attachments are used for all content associated with the ticket, including text content.  They will be modelled as MIME entities.

The ticket resource will support the GET and POST methods.

Whois Object

A ‘Whois object’ resource represents an object from the Whois system.

Apart from the ID that all objects have, a Whois object contains all of the Whois details from the underlying Whois record.

Whenever a Whois object is created or updated, the API will use the set of registered maintainers to satisfy the authorisation requirements of the update. In other words, it will not be necessary to manually add passwords to requests submitted to the API.

Unlike the other resources, the ‘list’ endpoints for Whois objects will be more restrictive, due to the volume of objects registered against some Member accounts.

API organisation

The API will be split into six high-level sections, each concentrating on one or more resource types:

• Internet resource management (internal)
  • Entity
  • Customer
  • Customer Assignment
  • Delegation
  • Aggregate Delegation
• Internet resource management (external)
  • Resource Request
  • Resource Transfer
  • Resource Return
• Reverse DNS
  • Reverse DNS Delegation
• Route
  • Route
• Whois
  • Maintainer
  • Whois Object
• Contact
  • Ticket

Certain sections deal with resource types that ‘belong’ to other sections, though.  For example, reverse DNS delegations include entity details.

Appendix

Background operations of the API

Entities

When an entity object is created, a Whois person object is also automatically created by the system and is tied to this entity object. Wherever this entity object is used, Whois objects that are directly related would also be updated/created with the Whois person object used as a contact, be it admin-c, tech-c or zone-c.

Customers

When a customer object is created, the system also automatically creates a maintainer object in Whois that is tied to the customer. This process happens in the background, with no indication through the API that it has happened other than the new maintainer appears in the maintainer list. The maintainer created through this process is used by the system to make changes to Whois when assignments are made, and is used as the mnt-routes of the inetnum/inet6num objects created for the customer’s assignments.

Assignments

When making an assignment to a customer, the system updates Whois by creating an inetnum/inet6num object with information based on the customer and its related associated records, principally entities.