Working with NorthStar RESTful APIs

Use the Juniper NorthStar APIs to monitor and control your TE-LSPs.

The current API definitions can be found on the NorthStar API v2 page.

You can use the APIs and extensions after you authenticate through the authentication API.

The NorthStar RESTful APIs are designed to enable access over HTTP to most of the same data and analytics that are available to you from both the NorthStar GUI and the NorthStar CLI.

REST basics

Many NorthStar users have little or no prior experience developing programs or scripts that make use of use RESTful APIs. For this reason, we are providing a breif introduction designed to help you with some basics about REST and what it means to access data and functionality using common conventions associated with REST. In addition, we are providing a few simple code examples that illustrate common uses of specific APIs.

REST (REpresentational State Transfer) is a set of useful conventions and principals about transfer of information over the World Wide Web.

How you're already using REST

Many Web services are now using the principals of REST in their design.

When you type a URL into your browser, like http://example.net, your browser software creates an HTTP header that identifies:

  • a desired action: GET ("get me this resource").

  • a target machine (www.domain-name.com).

When you update your credit card information to an online account, your browser software creates an HTTP header with a payload that contains your form data;

The HTTP header identifies:

  • a desired action: POST ("here's some update info").

  • a target machine (www.domain-name.com).

The payload contains:

  • form data to POST to a resource on the target machine.

Common HTTP verbs

The HTTP verbs (also known as methods) that are commonly used in RESTful requests are POST, GET, PUT, and DELETE. These are known as CRUD, for create, read, update, and delete operations. Additional HTTP methods exist, but are used less frequently, including PATCH, OPTIONS and HEAD, among others, but these are not used in the NorthStar APIs

Below is a table summarizing some helpful information about common HTTP methods:

CRUD
HTTP Verb CRUD Entire Collection (e.g. /customers) Specific Item (e.g. /customers/{id})
POST Create 201 (Created), 'Location' header with link to /customers/{id} containing new ID. 404 (Not Found), 409 (Conflict) if resource already exists..
GET Read 200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists. 200 (OK), single customer. 404 (Not Found), if ID not found or invalid.
PUT Update/Replace 404 (Not Found), unless you want to update/replace every resource in the entire collection. 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
DELETE Delete 404 (Not Found), unless you want to delete the whole collection—not often desirable. 200 (OK). 404 (Not Found), if ID not found or invalid.

Patterns for NorthStar RESTful Web services

RESTful Web services are commonly used for many familiar transactions over the Web, and their use is expanding.

RESTful requests to NorthStar will often follow patterns similar to the following request, which retrieves a full topology:


                https://<pcs_ip>:8443/NorthStar/API/v2/tenant/1/topology/1
            

The data in a response message body can range from a single entry to thousands of lines, depending on the request. The following example illustrates the kind of data you might see returned in response to a topology request:

Example topology data

Common NorthStar RESTful requests/response patterns