Getting Started

This section provides a quick overview of the API and how to get started.

Authentication

The first step is to authenticate using a JWT bearer token. Organization structures and roles depend on the authentication configuration used. For details on authentication, please consult the NICo REST auth module README.

API Version

The next step is to be aware of the API version being used. The API version can be retrieved by calling the Retrieve Metadata endpoint. In general, the API maintains backward compatibility with the previous versions. Any breaking changes are announced using a deprecation notice. Click on each API resource to see the deprecation notices.

Service Account Mode

Depending on the auth configuration used, the NICo REST API may be configured in Service Account mode. In this mode, API users can act as both Provider and Tenant as part of the same organization. If this is the case, the user must first retrieve the Service Account by making a call to the Retrieve Service Account endpoint. For service accounts, the Tenant entity is initialized as a privileged Tenant with targetedInstanceCreation capability enabled.

Provider or Tenant Mode

If NICo REST API is not configured in Service Account mode, the user should retrieve the Infrastructure Provider by making a call to the Retrieve Infrastructure Provider endpoint or the Tenant by making a call to the Retrieve Tenant endpoint.

In both cases, these calls initialize Provider and Tenant entities for the organization. All resources created are anchored to either the Provider or Tenant entity.

Once the Provider and the Tenant are initialized, the user can create resources by making calls to the appropriate endpoints.

Creating Site Level IP Blocks

To utilize a NICo Site, the Provider or Service Account holder must create IP Blocks for each network overlay defined in NICo Site configuration toml file.

To create an IP Block, the user must make a call to the Create IP Block endpoint.

Note: From this point onwards, a brief outline is provided for the typical API call flows for various use cases.

Typical API Call Flow for Service Account

• Retrieve available Sites using the Retrieve All Sites endpoint and choose a Site to create resources in. For Disconnected NICo installations where NICo REST is deployed alongside NICo Core, typically there will be a single Site available.
• For each Site IP Block, create a Network Allocation for the Tenant entity using the Create Allocation endpoint using the full prefix length. This will create a Tenant IP Block for each Site IP Block.
• Creating an Allocation will create the Tenant in NICo Core.
• Create a VPC using the Create VPC endpoint.
• Create a VPC Prefix or Subnet referencing the VPC and a Tenant IP Block
• If the Site supports Native Networking (FNN), create a VPC Prefix using the Create VPC Prefix endpoint. Otherwise the user should create a Subnet using the Create Subnet endpoint.
• Create an Operating System using the Create Operating System endpoint specifying iPXE script and user data.
• Retrieve available Machines on Site using the Retrieve All Machines endpoint
• Create an Instance specifying the VPC, VPC Prefix or Subnet, Operating System, and Machine

Typical API Call Flow for Provider

• Create a Tenant Account using the Create Tenant Account endpoint. Provider must know the Tenant org name.
• Once the Tenant has accepted the Tenant Account, the Provider can allocate resources to the Tenant.
• Retrieve available Sites using the Retrieve All Sites endpoint and choose a Site to create resources in.
• Create an Instance Type using the Create Instance Type endpoint
• Retrieve available Machines on Site using the Retrieve All Machines endpoint
• Update a Machine’s Instance Type using the Update Machine endpoint or assign multiple Machines to an Instance Type using the Create Instance Type/Machine Association endpoint
• Create a Compute Allocation for Tenant using the Create Compute Allocation endpoint referencing the Instance Type
• Creating any type of Allocation for a Tenant will create the Tenant in NICo Core.
• Create a Network Allocation for Tenant using the Create Allocation endpoint referencing a Site IP Block
• Creating a Network Allocation will create a Tenant IP Block

Typical API Call Flow for Tenant

• Accept the Tenant Account using the Update Tenant Account endpoint.
• Retrieve available Sites using the Retrieve All Sites endpoint and choose a Site to create resources in. Any Site where the Tenant has an Allocation will be returned.
• Create a VPC using the Create VPC endpoint.
• Retrieve available Site IP Blocks using the Retrieve All IP Blocks endpoint. Any IP Block for which the Tenant has received a Network Allocation from the Provider will be returned.
• Create a VPC Prefix or Subnet referencing the VPC and a Tenant IP Block
• Site supports Native Networking (FNN), create a VPC Prefix using the Create VPC Prefix endpoint
• Otherwise the user should create a Subnet using the Create Subnet endpoint
• Create an Operating System using the Create Operating System endpoint specifying iPXE script and user data.
• Retrieve available Instance Types using the Retrieve All Instance Types endpoint. Any Instance Type for which the Tenant has received a Compute Allocation from the Provider will be returned.
• Create an Instance specifying the VPC, VPC Prefix or Subnet, Operating System, and Instance Type