Imaster NCE-Campus V300R021C00 Introduction To Northbound APIs

iMaster NCE-Campus V300R021C00
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.
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.
Contents
1. RESTful Introduction
2. User Identity Authentication
3. RESTful APIs Provided by iMaster NCE-Campus
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.
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
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 HTTP header
Accept-Language:en_US
{
"userName": "[email protected]",
"password": "Aac@123456" 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 HTTP header
Location:https://example.com/controller/v2/tokens
{
"errcode": "0",
"errmsg": "get token successfully.",
"data": {
"expiredDate": "2016-10-25 12:03:37",
Response body
"token_id":"CA48D152F6B19D84:637C38259E6974E1778834812
8A430FEE150E874752CE754B6BF855281219925"
}
}
HTTP Headers
• iMaster NCE-Campus raises some restrictions on the HTTP headers of
RESTful requests and responses, covering the following parameters:
▫ Content-Type
▫ Accept
▫ X-ACCESS-TOKEN
▫ Accept-Language
Common HTTP Status Codes and
Their Meanings
HTTP
Description Common Error
Status Code
2xx Operation succeeded. N/A
400 Operation failed. See errmsg for error details.
401 Unauthorized. The token is incorrect or has expired.
• The administrator does not have the access permission.
403 Access denied
• The resource to be accessed does not exist.
The requested resource does
404 The resource requested in a GET request does not exist.
not exist.
The message body format in Content-Type is not set or the value of Content-Type is not
415
the request is not supported. application/json.
500 Internal error. N/A
503 Service unavailable. A service exception occurs.
Contents
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 API administrator account
Get Token
(/controller/v2/tokens) Site 1
Add, delete, modify, or query

devices. Site 2
(/controller/campus/v3/devices)
API administrator
Preset role
(for example,
(Open API operator)
Add, delete, modify, or query an [email protected])
SSID. Site 3
(/controller/campus/v3/network
config/site/{siteId}/apssid)
Site 4
Other API operations...
API Invoking Flow
Create an API
administrator.
POST/controller/v2/tokens
Content-Type: application/json When invoking an API, set both
Accept: application/json Content-Type and Accept to
Accept-Language: en_US application/json.
{
"password": "Huawei@123"
}
HTTP status 200 This is the

Obtain a token. { obtained token.
"errcode": "0",
"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
Accept: application/json
Invoke an API using for subsequent API requests.
Accept-Language: en_US
the obtained token. X-ACCESS-TOKEN: 30DE171572644A26:3EFC5288991E41AC871A4A5381226FABF8ED277571BC49D182B68
8676F42C3D5
User Identity Authentication Example 1:
Obtaining a Token
 A client sends a login authentication request to iMaster NCE-Campus.
cURL 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":"[email protected]","password":"Aac@123456"}'
HTTP POST /controller/v2/tokens HTTP/1.1

Host: 192.168.1.125:18002
{
"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",
"data": {
"expiredDate": "2016-10-25 12:03:37",
"token_id": "CA48D152F6B19D84:637C38259E6974E17788348128A430FEE150E874752CE754B6BF855281219925"
}
}
Delivering a Service
 The client sends a RESTful request carrying the obtained token to iMaster NCE-Campus
again to perform a service operation.
curl -k -s -L -i -X DELETE -H 'Content-Type: application/json' -H ‘Accept: application/json' -H 'Accept-Language: en_US' -H 'X-
cURL ACCESS-TOKEN:CA48D152F6B19D84:637C38259E6974E17788348128A430FEE150E874752CE754B6BF855281219925'
'https://192.168.1.125:18002/controller/campus/v1/networkservice/networkconfig/net/localuser/sites/fbb684c8-0d37-496f-
bafa-4b06d5151e2e/users/test'
HTTP DELETE /controller/campus/v1/networkservice/networkconfig/net/localuser/sites/fbb684c8-0d37-496f-bafa-

4b06d5151e2e/users/test HTTP/1.1
Host: 192.168.1.125:18002
Content-Type: application/jsonAccept:application/json
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
{
"errcode":"0",
"errmsg":""
}
Revoking the Token
 The client sends a session logout request to iMaster NCE-Campus.
cURL 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"}'
HTTP POST /restconf/operations/huawei-ac-access-token:revoke-token HTTP/1.1

Host: 192.168.1.125:18002
{
"input" : {
"token-id" : "CA48D152F6B19D84:637C38259E6974E17788348128A430FEE150E874752CE754B6BF855281219925"
}
}
 iMaster NCE-Campus sends a response message.

HTTP/1.1 200 OK
Server: example-server
Process of Invoking the User Authentication
API in the Multi-cluster Scenario
Create an API
administrator
Create an API under a region.
administrator. POST /controller/campus/api/v1/multiregion/tokens
Host: 192.168.1.125:18002 When invoking the API, set
Content-Type: application/json both Content-Type and
Accept: application/json Accept to application/json,
Accept-Language: en_US and set host to the IP address
{ of the global cluster in the
"userName": "[email protected]", multi-cluster system.
"password": "Huawei@123"
}
Obtain a token. HTTP status 200

{ Obtained token
"errcode": "0", and regionAddress
"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
header to the obtained token, and
Invoke an API using Host: 192.168.1.126:18002
set the host IP address to the value
the obtained token. of regionAddress.
X-ACCESS-TOKEN: 30DE171572644A26:3EFC5288991E41AC871A4A5381226FABF8ED277571BC49D182B68
8676F42C3D5
Contents
APIs Provided by iMaster NCE-Campus
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.
Quiz
Which of the following methods can be used to invoke RESTful APIs?
A. PUT
B. GET
C. POST
D. DELETE
Thank You
www.huawei.com

Imaster NCE-Campus V300R021C00 Introduction To Northbound APIs

Uploaded by

Copyright:

Available Formats

Imaster NCE-Campus V300R021C00 Introduction To Northbound APIs

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Imaster NCE-Campus V300R021C00 Introduction To Northbound APIs

Uploaded by

Copyright:

Available Formats

iMaster NCE-Campus V300R021C00

Introduction to Northbound APIs

▫ Understand how to invoke RESTful APIs.

2. User Identity Authentication

3. RESTful APIs Provided by iMaster NCE-Campus

2. User Identity Authentication

3. RESTful APIs Provided by iMaster NCE-Campus

Permission Role Managed object API administrator account

Add, delete, modify, or query

Other API operations...

HTTP status 200 This is the

HTTP POST /controller/v2/tokens HTTP/1.1

 iMaster NCE-Campus returns a token and its expiration time.

HTTP DELETE /controller/campus/v1/networkservice/networkconfig/net/localuser/sites/fbb684c8-0d37-496f-bafa-

 iMaster NCE-Campus returns the service operation result.

cURL curl -k -s -L -X DELETE -H 'Content-Type: application/json' -H ‘Accept: application/json' -H 'Accept-Language: en_US'

HTTP POST /restconf/operations/huawei-ac-access-token:revoke-token HTTP/1.1

 iMaster NCE-Campus sends a response message.

Obtain a token. HTTP status 200

2. User Identity Authentication

3. RESTful APIs Provided by iMaster NCE-Campus

Configuring DNS Configure a domain name.

Configuring a local user Configure a local user.

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.

Managing devices Create, modify, delete, and query devices.

You might also like