Guide That Contains This Content
[+] Expand All
[-] Collapse All

Connectivity Services Director REST API Overview

The Juniper Networks Connectivity Services Director APIs are based on the Representational State Transfer (REST) standards. REST defines a set of principles for defining Web services, including how a system’s resource states are transferred over HTTP. Clients can be written in any language that sends HTTP requests.

You use standard HTTP methods to access the Connectivity Services Director APIs. For example, HTTP GET is used by a client application to retrieve a resource, get data from a Web server or to execute a query. Common HTTP methods for REST are:

  • GET – Retrieve a resource from the server.
  • POST – Update a resource on the server.
  • PUT – Create a resource state on the server.
  • DELETE – Remove a resource state on the server.

The following media types are supported:

  • For APIs that employ the GET method—Accept is used because only a Response is the involved operation here. The Accept type determines the type of the Response obtained, which can be either in XML or in JSON format.
  • For APIs that employ the POST method—Content-type needs to be used, which determines the type of the input payload or request that is sent.
  • For APIs that employ the PUT method—Content-type needs to be used, which determines the type of the input payload or request that is sent.
  • For APIs that employ the DELETE method—Accept needs to be use because only a Response is the involved operation here

    The Accept type determines the type of the response obtained, which can be either in XML or in JSON format. For example, for the Add Customer API, the Content and Accept types for XML are as follows:

    XML

    Content-Type—application/vnd.net.juniper.space.customer-management.customers+xml

    Accept—application/vnd.net.juniper.space.customer-management.customers-status+xml

Retrieved resources are displayed in human-readable format. Connectivity Services Director APIs return data in XML or JavaScript Object Notation (JSON).

The following RESTful Web Services are exposed under the Junos Space Connectivity Services Director root URI:

  • Customers
  • Provider edge (PE) devices
  • Prestage devices and management of multihomed groups
  • Resource pools
  • Service definitions for point-to-point (P2P), VPLS, and Layer 3 VPN (L3VPN) services
  • Service orders for P2P, VPLS, and L3VPN services
  • Service operations for P2P, VPLS, and L3VPN services
  • Service templates for P2P, VPLS, and L3VPN services
  • Bulk operations for P2P services
  • Functional and configuration audit
  • QoS profiles for services
  • CFM profiles for services
  • Performance management (PM) statistics
  • Service definitions and service orders for LSP services
  • OAM services for LFM, CFM, and SLA iterators
  • Services for RFC 2544-based benchmarking tests
  • Timing services for synchronous Ethernet and PTP

URI: /api/juniper/space

Connectivity Services Director RESTful Web Services provide programmatic access to the resources that are defined in Junos Space Connectivity Services Director. Connectivity Services Director RESTful Web Services follow the same standards and conventions as the Junos Space Network Application Platform RESTful Web Services. The Connectivity Services Director RESTful Web Services are exposed under the Juniper Networks Junos Space RESTful Web Services root URI (/api). Connectivity Services Director-related RESTful Web Services are exposed under the /api/juniper/space URI.

Example resource returned in XML format

<Data xmlns="services.schema.networkapi.jmp.juniper.net">
<Customers>
	<Customer>
		<Common>
			<Name>Customer_005</Name>
		</Common>
		<AccountNo>40132324005</AccountNo>
		<ContactName>customer005</ContactName>
		<ContactEmail>customer005@example.com</ContactEmail>
	</Customer>
</Customers>
</Data>
 

Example resource returned in JSON format

{ "Data" : { "Customers" : { "Customer" : { "AccountNo" : 40132324005,
              "Common" : { "Name" : "Customer_005" },
              "ContactEmail" : "customer005@example.com",
              "ContactName" : "customer005"
            } } } }

Format and Conventions of RESTful Web Services

The media type for the Connectivity Services Director application must have the following format:

application/vendor.space.service.type+syntax;version=version number or

vendor.space.service.type+syntax;version=version number

For example, application/vnd.net.juniper.space.monitoring.alarmscount+json;version=1

Table 1 describes these parameters.

Table 1: Media parameters

Parameter

Description

vendor

Vendor of the media type. Media types defined by Juniper Networks use vnd.net.juniper. Third-parties must use their own vendor string when they define their own Web services in their applications that are deployed on Junos Space.

service

Name of the Junos Space-specific service. Service names are all lowercase alphanumeric tokens with hyphen separators; for example, device-management, incident-management.

type

Type of resource. Types are all lowercase alphanumeric tokens with hyphen separators; for example, device, incident.

syntax

Representation of the resource, for example xml..

version

Version of the API; versions begin with the numeral 1.

REST standards are well-described in books and on the Internet. It is not the intent of this guide to discuss the RESTful architecture. This document deals with the REST APIs exposed by Connectivity Services Director.

For information about Junos Space SDK, refer to Junos Space SDK .

Payload and Response Types Supported in XML and JSON Formats

The payload or request can be in both the XML format and JSON format, although this reference guide illustrates only the XML type input or payload in the sample APIs. An API is available for converting any given XML payload into a JSON payload. See Conversion of XML Format to JSON Format, for detailed information on converting the XML format into a JSON format. Responses to the API request calls can be in both the XML format and JSON format, although this reference guide describes only the XML type responses in the samples.

Conversion of XML Format to JSON Format

For the ease of the users, an additional API has been provided for converting the XML inputs to JSON format. If the XML inputs pertaining to the NetworkAppsAPI are given as input, then the corresponding JSON format output can be obtained from this API.

URI

api/space/nsas/xml-json/convert">

HTTP Method

GET

Consumes

application/xml

Content-Type

application/json

Produces

Collects all the configured E-LINE LDP service orders.

Input (Converting the AddCustomer XML-Input to JSON-Input)

Sample XML Input

<Data xmlns="services.schema.networkapi.jmp.juniper.net">
<Data xmlns="services.schema.networkapi.jmp.juniper.net">
<Customers>
	<Customer>
		<Common>
			<Name>Customer_005</Name>
		</Common>
		<AccountNo>40132324005</AccountNo>
		<ContactName>customer005</ContactName>
		<ContactEmail>customer005@example.com</ContactEmail>
	</Customer>
</Customers>
</Data>
 

Output (JSON Format of the Preceding Input)

Sample XML Output

<Data xmlns="services.schema.networkapi.jmp.juniper.net">

{"Data":{"Customers":{"Customer":{"Common":{"Name":"Customer_005"},
"AccountNo":40132324005,"ContactName":"customer005","
ContactEmail":"customer005@example.com"}}}}

Note: We recommend that you read this guide in conjunction with the Network Director API Reference for information about the REST APIs that you can configure for some of the functionalities available in views other than Service view of Connectivity Services Director. These APIs also define the fault and alarm notification APIs.

Modified: 2016-06-09