Introduction

Welcome! This is the API reference for the NetFoundry Customer Management Service, a lexicon of all possible API operations and their parameters. More conceptually and procedurally oriented guides and code samples may be found by visiting the Developer Portal.

Overview

HTTP verbs

NetFoundry adheres closely to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

Verb	Usage
`GET`	Used to retrieve a resource
`POST`	Used to create a new resource
`PUT`	Used to update an existing resource, full updates only
`PATCH`	Used to update an existing resource, partial updates
`DELETE`	Used to delete an existing resource

GET

Used to retrieve a resource

POST

Used to create a new resource

PUT

Used to update an existing resource, full updates only

PATCH

Used to update an existing resource, partial updates

DELETE

Used to delete an existing resource

HTTP status codes

NetFoundry adheres closely to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

Status code	Usage
`200 OK`	The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
`201 Created`	The request has been fulfilled and resulted in a new resource being created.
`202 Accepted`	The request has been accepted and is being processed asynchronously Standard response for successful HTTP requests which invoke back-end services.
`204 No Content`	The server successfully processed the request, but is not returning any content.
`400 Bad Request`	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
`401 Unauthorized`	The request lacks valid authentication credentials for the target resource.
`403 Forbidden`	The request is authenticated with valid credentials however that set of credentials is not authorized to access this resource.
`404 Not Found`	The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

200 OK

The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled and resulted in a new resource being created.

202 Accepted

The request has been accepted and is being processed asynchronously Standard response for successful HTTP requests which invoke back-end services.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

401 Unauthorized

The request lacks valid authentication credentials for the target resource.

403 Forbidden

The request is authenticated with valid credentials however that set of credentials is not authorized to access this resource.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

Pagination

Paginated services will accept the following optional request parameters:

Table 1. Request parameters
Path	Type	Optional	Description
page	Integer	true	Page you want to retrieve, 0 indexed and defaults to 0.
size	Integer	true	Size of the page you want to retrieve, defaults to 1000.
sort	String	true	Sort a list of resources by one or more of their properties e.g. `?sort=firstname,asc&sort=lastname,desc`. The default order is `asc`.

Pagination response has following structure:

Table 2. Response structure
Path	Type	Optional	Description
content	Array[Object]	false	Actual items.
totalElements	Integer	false	Total count.
totalPages	Integer	false	Total pages with current page size.
last	Boolean	false	If this page is the last one.
numberOfElements	Integer	false	Actual size of content array (number of items).
first	Boolean	false	If this page is the first one.
sort	Object	true	Sort information object.
size	Integer	false	Requested size of the page.
number	Integer	false	Page number.
empty	booloean	false	If this page is empty.

Content Types

You may request a content type or alternative representation or both for a resource or list of resources with the Accept header.

Request a Content Type

The default content type of a response is HAL+JSON when the Accept header is absent from the request.

Embed Child Resources

When requesting an individual or list of resources you may additionally request child resources be embedded in the response by sending query parameter embed=all or embed={{child}}. The valid names for child resources are the keys in _links, except things that are not children like self, customer. The table below details how the format of the embedded lists varies depending upon the requested content-type. Embedding is always one level deep. Put another way, the network is like the trunk which may embed branch lists (e.g. customer resource assignments), and branches may embed individual leaves.

Request

This example requests that the "customer-resource-assignments" child resource list be embedded in the response that describes a particular customer.

GET /customers/${customerId}?embed=customer-resource-assignments
Accept: application/hal+json

Response Template

The full response would be prohibitively verbose, and so this template will demonstrate the response structure for a single resource with embedded child list "edge-routers".

{
  {{ customer properties }},
  "_embedded": {
    "customer-resource-assignments": {{ list of resource assignments }}
  },
  "_links": {{ dictionary of related resources}}
}

Notation MIME Type Embedded Format

Notation	MIME Type	Embedded Format
HAL+JSON (default)	application/hal+json	The response has key `_embedded` which will itself have keys for each type of resource. For example, `_embedded.customer-resource-assignments` is typical when requesting an embedded list of customer resource assignments for a particular customer or list of customers.
JSON	application/json	Each requested, embedded list will appear in a top-level key e.g. `.customer-resource-assignments`.
YAML	application/x-yaml	Each requested, embedded list will appear in a top-level key where the resource type has been transposed from kebab-case to camel-case e.g. `customer-resource-assignments` becomes top-level key `customerResourceAssignments`.
CSV	text/csv	Heterogeneous embedded resources can not be expressed as CSV because they would require different column headers.

HAL+JSON (default)

application/hal+json

The response has key _embedded which will itself have keys for each type of resource. For example, _embedded.customer-resource-assignments is typical when requesting an embedded list of customer resource assignments for a particular customer or list of customers.

JSON

application/json

Each requested, embedded list will appear in a top-level key e.g. .customer-resource-assignments.

YAML

application/x-yaml

Each requested, embedded list will appear in a top-level key where the resource type has been transposed from kebab-case to camel-case e.g. customer-resource-assignments becomes top-level key customerResourceAssignments.

CSV

text/csv

Heterogeneous embedded resources can not be expressed as CSV because they would require different column headers.

Resources

Customers

Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customers/get-customers/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customers/get-customer/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customers/create-customer/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customers/patch-customer/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customers/put-customer/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customers/delete-customer/auto-section.adoc[]

Customer Resource Assignments

Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customer-resource-assignments/get-customer-resource-assignments/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customer-resource-assignments/get-customer-resource-assignment/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customer-resource-assignments/create-customer-resource-assignment/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customer-resource-assignments/patch-customer-resource-assignment/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customer-resource-assignments/put-customer-resource-assignment/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customer-resource-assignments/delete-customer-resource-assignment/auto-section.adoc[]

Signups

Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/signups/get-signups/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/signups/get-signup/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/signups/signup/auto-section.adoc[] Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/signups/delete-signup/auto-section.adoc[]

Customer Offboard

Unresolved directive in index.adoc - include::/Users/prashantsavadi/git/customer-management/target/generated-snippets/customers/offboard-customer-self/auto-section.adoc[]

NetFoundry Customer Management Service Guide