iMaster NCE-Campus V300R20C10
Introduction to Northbound APIs
Page 0
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Foreword
• This course describes RESTful open APIs provided by iMaster NCE-Campus for
northbound applications, explains the functions of these APIs, and provides API
invoking examples.
Page 1
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Objectives
• Upon completion of this course, you will be able to:
▫ Understand the main functions that can be implemented by RESTful APIs.
▫ Understand how to invoke RESTful APIs.
Page 2
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Contents
1. RESTful Introduction
2. User Identity Authentication
3. RESTful APIs Provided by iMaster NCE-Campus
Page 3
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Overview
• iMaster NCE-Campus provides a collection of RESTful APIs. Northbound applications can
invoke these APIs using HTTPS to deliver services to southbound devices and query data.
Page 4
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
API Standards
• The methods of invoking all RESTful APIs provided by iMaster NCE-Campus comply with the
following standard:
• When invoking a RESTful API provided by iMaster NCE-Campus, the client needs to use the
HTTPS protocol to access the following IP address and port:
▫ Northbound floating IP address (used for login to the iMaster NCE-Campus web UI)
▫ Port 18002
Page 5
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Request Packet Format
• The format of request packets is as follows.
Example
Description
POST /controller/v2/tokens HTTP/1.1
Host: 192.168.1.125:18002
Request URL
Content-Type:application/json
Accept:application/json
Accept-Language:en_US
HTTP header
{
"userName": "admin@ac.branch",
"password": "Aac@123456"
}
Page 6
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Request body
Response Packet Format
• The format of response packets is as follows.
Example
Description
HTTP/1.1 200 OK
Status code
Date:Mon, 23 Apr 2016 17:02:00 GMT
Server:example-server
Location:https://example.com/controller/v2/tokens
HTTP header
{
"errcode": "0",
"errmsg": "get token successfully.",
"data": {
"expiredDate": "2016-10-25 12:03:37",
"token_id":"CA48D152F6B19D84:637C38259E6974E1778834812
8A430FEE150E874752CE754B6BF855281219925"
}
}
Page 7
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Response body
HTTP Headers
• iMaster NCE-Campus raises some restrictions on the HTTP headers of
RESTful requests and responses, covering the following parameters:
Page 8
▫
Content-Type
▫
Accept
▫
X-ACCESS-TOKEN
▫
Accept-Language
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Common HTTP Status Codes and
Their Meanings
HTTP
Description
Status Code
Common Error
2xx
Operation succeeded.
N/A
400
Operation failed.
See errmsg for error details.
401
Unauthorized.
The token is incorrect or has expired.
403
Access denied
• The administrator does not have the access permission.
• The resource to be accessed does not exist.
404
The requested resource does
not exist.
The resource requested in a GET request does not exist.
415
The message body format in
the request is not supported.
Content-Type is not set or the value of Content-Type is not
application/json.
500
Internal error.
N/A
503
Service unavailable.
A service exception occurs.
Page 9
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Contents
1. RESTful Introduction
2. User Identity Authentication
3. RESTful APIs Provided by iMaster NCE-Campus
Page 10
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
User Identity Authentication
• iMaster NCE-Campus determines user permissions when a user logs in to the system using a username
and a password. The account used to invoke RESTful APIs must be attached with the open API operator
role and have the permission on the managed objects.
Permission
Role
Managed object
Get Token
(/controller/v2/tokens)
Site 1
Add, delete, modify, or query
devices.
(/controller/campus/v3/devices)
Site 2
Add, delete, modify, or query an
SSID.
(/controller/campus/v3/networkco
nfig/site/{siteId}/apssid)
API administrator
(for example,
api@huawei.com)
Preset role
(Open API operator)
Site 3
Site 4
Other API operations...
Page 11
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
API administrator account
API Invoking Flow
Create an API
administrator.
POST/controller/v2/tokens
Content-Type: application/json
Accept: application/json
Accept-Language: en_US
{
"userName": "sapi@huawei.com",
"password": "Huawei@123"
}
Obtain a token.
Invoke an API using
the obtained token.
Page 12
When invoking an API, set both
Content-Type and Accept to
application/json.
HTTP status 200
This is the obtained
{
token.
"errcode": "0",
"errmsg": "get token successfully.",
"data": {
"expiredDate": "2018-03-07 17:17:48",
"token_id":"30DE171572644A26:3EFC5288991E41AC871A4A5381226FABF8ED277571BC49D182B68
8676F42C3D5"
}
}
POST /xxxx
Set X-ACCESS-TOKEN to the
Content-Type: application/json
obtained token in the header for
Accept: application/json
subsequent API requests.
Accept-Language: en_US
X-ACCESS-TOKEN:
30DE171572644A26:3EFC5288991E41AC871A4A5381226FABF8ED277571BC49D182B68
8676F42C3D5
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
User Identity Authentication Example 1:
Obtaining a Token

A client sends a login authentication request to iMaster NCE-Campus.
cURL
HTT
P

curl -k -s -L -X POST -H 'Content-Type: application/json' -H ‘Accept: application/json' -H 'Accept-Language: en_US'
'https://192.168.1.125:18002/controller/v2/tokens' -d '{"userName":"admin@ac.branch","password":"Aac@123456"}'
POST /controller/v2/tokens HTTP/1.1
Host: 192.168.1.125:18002
Content-Type: application/json
Accept: application/json
Accept-Language: en_US
{
"userName": "admin@ac.branch",
"password": "Aac@123456"
}
iMaster NCE-Campus returns a token and its expiration time.
HTTP/1.1 200 OK
Date:Mon, 23 Apr 2016 17:02:00 GMT
Server:example-server
Location:https://192.168.1.125:18002/controller/v2/tokens
{
"errcode": "0",
"errmsg": "get token successfully.",
"data": {
"expiredDate": "2016-10-25 12:03:37",
"token_id": "CA48D152F6B19D84:637C38259E6974E17788348128A430FEE150E874752CE754B6BF855281219925"
}
}
Page 13
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
User Identity Authentication Example 2:
Delivering a Service

The client sends a RESTful request carrying the obtained token to iMaster NCE-Campus again
to perform a service operation.

cURL
curl -k -s -L -i -X DELETE -H 'Content-Type: application/json' -H ‘Accept: application/json' -H 'Accept-Language: en_US' -H 'XACCESS-TOKEN:CA48D152F6B19D84:637C38259E6974E17788348128A430FEE150E874752CE754B6BF855281219925'
'https://192.168.1.125:18002/controller/campus/v1/networkservice/networkconfig/net/localuser/sites/fbb684c8-0d37-496f-bafa4b06d5151e2e/users/test'
HTT
P
DELETE /controller/campus/v1/networkservice/networkconfig/net/localuser/sites/fbb684c8-0d37-496f-bafa4b06d5151e2e/users/test HTTP/1.1
Host: 192.168.1.125:18002
Content-Type: application/jsonAccept:application/json
Accept: application/json
Accept-Language: en_US
X-ACCESS-TOKEN:CA48D152F6B19D84:637C38259E6974E17788348128A430FEE150E874752CE754B6BF855281219925
iMaster NCE-Campus returns the service operation result.
HTTP/1.1 200 OK
Date:Sat,24 Feb 2018 14:48:34 GMT
Server: example-server
Content-Type: application/json
{
"errcode":"0",
"errmsg":""
}
Page 14
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
User Identity Authentication Example 3:
Revoking the Token

The client sends a session logout request to iMaster NCE-Campus.
cURL
HTT
P

curl -k -s -L -X DELETE -H 'Content-Type: application/json' -H ‘Accept: application/json' -H 'Accept-Language: en_US'
'https://192.168.1.125:18002/controller/v2/tokens' -d '{"token":
"CA48D152F6B19D84:637C38259E6974E17788348128A430FEE150E874752CE754B6BF855281219925"}'
POST /restconf/operations/huawei-ac-access-token:revoke-token HTTP/1.1
Host: 192.168.1.125:18002
Content-Type: application/json
Accept: application/json
Accept-Language: en_US
{
"input" : {
"token-id" : "CA48D152F6B19D84:637C38259E6974E17788348128A430FEE150E874752CE754B6BF855281219925"
}
}
iMaster NCE-Campus sends a response message.
HTTP/1.1 200 OK
Server: example-server
Content-Type: application/json
Page 15
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Process of Invoking the User Authentication
API in the Multi-cluster Scenario
Create an API
administrator.
Obtain a token.
Invoke an API using
the obtained token.
Page 16
Copyright © 2021 Huawei Technologies
Create an API
administrator
under a region.
POST /controller/campus/api/v1/multiregion/tokens
Host: 192.168.1.125:18002
Content-Type: application/json
Accept: application/json
Accept-Language: en_US
{
"userName": "sapi@huawei.com",
"password": "Huawei@123"
}
When invoking the API, set
both Content-Type and
Accept to application/json,
and set host to the IP address
of the global cluster in the
multi-cluster system.
HTTP status 200
{
Obtained token and
"errcode": "0",
regionAddress
"errmsg": "get token successfully.",
"data": {
"expiredDate": "2018-03-07 17:17:48",
"token_id":"30DE171572644A26:3EFC5288991E41AC871A4A5381226FABF8ED277571BC49D182B68
8676F42C3D5",
"regionName": "region1",
"regionAddress": "192.168.1.126"
}
}
POST /xxxx
Set X-ACCESS-TOKEN in the
Content-Type: application/json
header to the obtained token, and
Host: 192.168.1.126:18002
set the host IP address to the value
Accept: application/json
of regionAddress.
Accept-Language: en_US
X-ACCESS-TOKEN:
30DE171572644A26:3EFC5288991E41AC871A4A5381226FABF8ED277571BC49D182B68
Co.,8676F42C3D5
Ltd. All rights reserved.
Contents
1. RESTful Introduction
2. User Identity Authentication
3. RESTful APIs Provided by iMaster NCE-Campus
Page 17
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
APIs Provided by iMaster NCE-Campus
Page 18
API
Description
Obtaining a token
Obtain a token for interconnection with a third-party system.
Configuring DNS
Configure a domain name.
Configuring a local user
Configure a local user.
Protocol control
Configure the device access protocol, for example, HTTP.
Modifying a switch’s management VLAN
Modify the management VLAN of a switch.
Configuring switch interfaces
Configure and query interfaces on a switch.
Configuring MSTP
Configure MSTP on a switch.
Configuring a TACACS server
Perform TACACS server configurations on switches.
Configuring an NTP server
Configure the time zone and NTP server on a device.
Managing sites
Create, modify, delete, and query sites. Add devices to and remove devices from sites.
Managing devices
Create, modify, delete, and query devices.
Restoring device factory defaults
Restore devices to their factory defaults in batches.
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Quiz
Which of the following methods can be used to invoke RESTful APIs?
A. PUT
B. GET
C. POST
D. DELETE
Page 19
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.
Thank You
www.huawei.com
Page 20
Copyright © 2021 Huawei Technologies Co., Ltd. All rights reserved.