Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

RESTful API Overview

The 100% API architecture of Juniper Mist backs every visible feature in the Juniper Mist portal. Anything that you can do in the portal, you can automate at scale by using the API. Representational State Transfer (REST) is a stateless client-server architecture with a uniform interface. Since machines have no use for a user interface, APIs allow for a defined and faster way for machines to communicate with each other. APIs also enable you and other users to create your own way of interacting with systems and applications. You can even create custom features.

The Juniper Mist API is available to any customer with a Juniper Mist account.

Juniper Mist API Architecture

Juniper Mist uses REST APIs, which use HTTP methods (GET, POST, PUT, and DELETE) to transfer data in JavaScript Object Notation (JSON) format.

As shown below, you can interact with Mist using the RESTful APIs in multiple ways.

RESTful API Requests

Using RESTful APIs follows a similar practice to the CRUD (CREATE, READ, UPDATE, DELETE) methodology used in development. These are the four basic actions or functions used when working with data.

Table 1: Basic CRUD Actions
CRUD HTTP/REST
Create POST
Read GET
Update PUT
Delete DELETE

REST commands include:

  • POST: Create an object.—POST overwrites any existing values with those contained in the payload. Values that are not specified in the POST payload are reverted to their original values.

  • GET: List objects.—GET returns the value of a resource or a list of resources, depending on whether an identifier is specified.

    • GET /api/v1/orgs/:org_id/site

      returns a list of sites belonging to the :org_id.

    • GET /api/v1/sites/:site_id

      returns information about the site specified by the :site_id.

  • PUT: Update an object.—PUT modifies all specified values in the payload. Any fields not specified in the payload are left intact.

  • DELETE: Remove an object.—DELETE removes a resource.

To perform any of the above commands on the REST API, you need to fulfill a few requirements in each request, such as:

  • Authentication: You can use an API token, Juniper Mist login credentials, or an external OAuth2 provider

    Note:

    If you are already logged in on manage.mist.com, you can simply open a new browser tab and go to https://api.mist.com/api/v1/self/apitokens and click the POST button. This will automatically create a new api user token.

    See Create API Tokens for more information about tokens.

  • HTTP Header: This header specifies the content and the authorization type, as follows:

    • For Juniper Mist, the content type is always application/json.

    • The authorization can be a token or a cookie (including CSRF token and session ID).

  • API Endpoint

  • JSON Payload

API Endpoint URL Format

The API endpoint URL has two parts:

  • API Endpoint—The endpoint for the global region that your Juniper Mist organization is associated with. See API Endpoints and Global Regions.

  • Function—Everything after the API endpoint represents the function that the API will call.

Example

https://<api-endpoint>/api/v1/sites/:<site-id>/stats/devices/:<device_id>.

Note:

You would replace the bracketed items with the actual values for your API endpoint, site ID, and device ID.

Everything after <api-endpoint> is the function. The call goes to the global cloud and requests the statistics for the specified device at the specified site.

JSON Payload

Different functions require different elements in the JSON payload. You can view the required details in the API documentation.

How to view the API documentation:

  1. Log in to your Juniper Mist portal.

  2. Click the Help button (near the top right corner of the screen).

  3. Click API Documentation.

API Rate Limiting

Juniper Mist limits API calls to 5,000 per hour. If you need a higher rate limit, contact Juniper support about your use case.

Note:

To prevent brute-force attacks, the login API (/api/v1/login) is rate-limited after three login failures.

API Authentication Options

The Juniper Mist API allows three options for requesting authentication:

  • Basic Authentication—Token

    • Secure it like a password.

    • For instructions about creating an API token, see Create API Tokens.

  • HTTP Login— Username and Password

    • Is like a dashboard login.

    • Can be two-factor authentication.

  • OAuth2

    • Account must be linked to an OAuth provider.

    • Requires browser access.

A Simple API Example

Using the Django API interface, you can make your first API call. After logging in to Mist, open a new window using the same browser and enter the URL https://api.mist.com/api/v1/self.

This is equivalent to making this API call GET /api/v1/self.

The result, shown above, displays the privileges assigned to you for the organizations and sites you are associated with.

Related Documentation