RESTful API Overview

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.

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

API Endpoint URL Format

The API endpoint URL has two parts:

• API Host ( or Endpoint)—The endpoint for the global region that your Juniper Mist organization is associated with. These endpoints are listed in API Endpoints and Global Regions.

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

Example

https://{api-host}/api/v1/sites/{site_id}/stats/devices/{device_id}.

https://api.mist.com/api/v1/sites/13b0ee00-121a-456e-84e0-ead3008bc2f2/stats/devices/00000000-0000-0000-1000-d420b08532eb

Note:

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

Everything after {api-host} is the function. The call goes to the global cloud and requests the statistics for the specified device at the specified site.

The next section takes a deeper look at the structure that makes up an API call.

API Call Structure

The following image is an example of an API call and the different components that make it up.

Table 2: API Call Components

API Call Component	Description
HTTP Method	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. When updating with a PUT, simple values (strings or numbers) not specified in the payload keep their existing values. If the value contains a data structure such as an array or an object, the values included in the payload will replace that structure in its entirety. Keep this in mind to avoid unwanted changes to existing values. DELETE—Remove an object.—DELETE removes a resource.
Host (or API Endpoint)	Determines the Mist Cloud to use (Global 01, EMEA 01, etc). The endpoint for the global region that your Juniper Mist organization is associated with. See API Endpoints and Global Regions.
Version	The API version to use (currently, all APIs use v1).
Scope	Indicates the level that the request is being done at. Examples include msp, org, site, self, register, installer, const, and so on.
Scope ID	Identifies the scope to use.
Object	The type of object to use (Device, WLAN, and so on).
Object ID	Identifies the object to request.

To perform any of the above REST commands (POST, GET, PUT, DELETE) 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 to indicate who you are and what you have access to during the authentication process.

  • For more detail on the various authentication methods, see Authentication.

    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).

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

• JSON Payload

The following table provides examples for the different parts that make up a RESTful API request.

Table 3: RESTful API Request examples

CRUD Operation	HTTP Header Authentication	Endpoint URL	Payload (JSON)
GET	API Token	https://api.mist.com/api/v1/sites/:site_id/wlans
DELETE	CSRF Token, Session ID	https://api.mist.com/api/v1/sites/:site_id/wlans/:wlan_id
POST	CSRF Token, Session ID	https://api.mist.com/api/v1/orgs/:org_id/inventory	{["<claim_code>"]}
PUT	API Token	https://api.mist.com/api/v1/sites/:site_id/wlans/:wlan_id	{"ssid" : "New Name"}

JSON Payload

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

The following is a sample API call and the response (JSON payload).

API call:

Response (JSON Payload):

API Rate Limiting

Juniper Mist limits API calls to 5,000 per hour. If you need to make more than 5,000 calls per hour, Create a Support Ticket.

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— User name and Password

  • Is like a dashboard login.

  • Can be two-factor authentication.

• OAuth2

  • Account must be linked to an OAuth provider.

  • Requires browser access.

For more information about Authentication, see the Mist API Reference.

A Simple API Example

The Django API interface is a web-based interface where you can perform CRUD operations within the API. See Use the Django Web Interface to Make API Changes.

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 the URL for the the Global 01 cloud. If you are using another cloud, this URL will be different.

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.