CPS MOG API Reference, Release

Transcription

1 CPS MOG API Reference, Release First Published: Last Modified: Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA USA Tel: NETS (6387) Fax:

2 THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB s public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental. All printed copies and duplicate soft copies are considered un-controlled copies and the original on-line version should be referred to for latest version. Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on the Cisco website at Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1721R) CPS Mobile Orchestration Gateway API Reference 2017 Cisco Systems, Inc. All rights reserved.

3 CONTENTS CONTENTS... III CHAPTER 1 MOG API REFERENCE... 6 CHAPTER 2 HEALTH CHECK API... 7 URI... 7 CHAPTER 3 ONBOARDING API... 8 TYPES OF USERS... 9 URI... 9 TENANTS Super Tenants Tenants/Enterprises Onboarding Tenant Methods Onboarding Tenant Request Fields SUBSCRIBERS Onboarding Subscriber Methods Onboarding Subscriber Request Fields User Privileges for APIs PUBLISHING APIS SUBSCRIBING TO APIS /ONBOARDING/TENANT POST Request Response Curl Example GET Request Response Curl Example PUT Request Response Curl Example DELETE Request Response Curl Example /ONBOARDING/TENANT/LIST GET Response Curl Example /ONBOARDING/SUBSCRIBER POST Request Response iii

4 Contents Curl Example GET Request Response Curl Example PUT Request Response Curl Example DELETE Request Response Curl Example /ONBOARDING/SUBSCRIBER/LIST GET Request Response Curl Example /ONBOARDING/API/LIST GET Response Curl Example CHAPTER 4 AUTHENTICATION API AUTHENTICATION TOKEN OVERVIEW Token Generation Token Usage Token Expiry Token Regeneration /AUTH/TOKEN POST Response Curl Example GET Response Curl Example PUT CHAPTER 5 UPDATEQOS URI Session Identifier UPDATE QOS SESSIONS AND METHODS Session Creation Session Update Session Delete Session Read Update QoS Submission Response UPDATE QOS REQUEST FIELDS INTENT PARAMETER FOR DEFAULT BEARER /NETWORK/DEFINE/QOSTYPE/VERSION POST Request Response iv Cisco Policy Suite MOG API reference

5 Contents Curl Example GET Request Response Curl Example /NETWORK/DEFINE/QOSTYPE/VERSION/SESSIONID PUT Request Response Curl Example DELETE Request Response Curl Example GET Request Response Curl Example CHAPTER 6 SESSION CALLBACK /CREATE_CALLBACK POST Request /PUT_CALLBACK POST /DELETE_CALLBACK POST VPASCALLBACK POST v

6 Chapter 1 MOG API Reference Mobile Orchestration Gateway (MOG) provides JSON format RESTful APIs. You can use the APIs to perform the following operations: Onboard tenants and users Generate and use token based authentication Dynamically modify the QoS of a subscriber For more information about MOG, see the CPS Mobile Orchestration Gateway Guide. 6

7 Chapter 2 Health Check API You can use the MOG Health Check API to verify the health of MOG APIs. URI The following format specifies the URI of the Health Check API: Examples: For HTTP Response: 200 curl -k API Server is running For HTTP Response: 503 curl -k <html><body><h1>503 Service Unavailable</h1> No server is available to handle this request. </body></html> 7

8 Types of Users Chapter 3 Onboarding API You can use the onboarding API to onboard or create tenants and subscribers. Onboarding is the process of authorizing enterprises, administrators of the enterprise, and the users of the enterprise to use MOG APIs. Before using the MOG APIs, you must onboard the users. 8

9 Types of Users Types of Users MOG includes the following types of users: Tenants Subscribers URI The URI of the onboarding API is specified in the following format: or subscriber> 9

10 Tenants Tenants Super Tenants MOG includes two types of tenants based on privileges: Super tenants are root administrators who has complete privileges and can perform the following functions: Onboard enterprise administrators or tenants. View, modify, and delete enterprise administrators or tenants. Access all onboarding APIs and can perform all actions on behalf of tenant/subscriber. Super tenant authentication parameters are managed using Policy Builder. As a super tenant, only you can onboard a tenant. Use the following URI to onboard a tenant: If you want to perform any other operation on a tenant, pass the domain of the tenant as a query parameter to the API requests as shown in the following example: Only a super tenant can delete tenants. Similarly, as a super tenant, if you want to perform any operation on a subscriber, pass the tenant's domain and subscriber's username as query parameters to the API request as shown in the following example: Tenants/Enterprises An enterprise administrator or a tenant can perform the following functions: Onboard, modify, or delete subscribers. Access own account and that of subscribers who are part of the enterprise. Publish APIs for their subscribers to use As a tenant or administrator, you can add subscribers using the following URI: As a tenant or administrator, if you want to perform any other operation on a subscriber, pass the subscriber s username as a query parameter to the API request as shown in the following example: Onboarding Tenant Methods The following table describes the Onboarding API operations and their respective methods: API Request URL HTTP Method Access Level Create /onboarding/tenant POST Super Tenant 10

11 Tenants API Request URL HTTP Method Access Level Update /onboarding/tenant PUT Super Tenant Tenant Admin Delete /onboarding/tenant DELETE Super Tenant Detail /onboarding/tenant GET Super Tenant Tenant Admin List /onboarding/tenant/list GET Super Tenant Onboarding Tenant Request Fields The following tables describe the fields used in the JSON payload of the Onboarding Tenant API request: Mandatory Fields Variable Type Description username admin.username string Tenant/Enterprise username. The same username along with the domain is used for authentication in all the subsequent API's initiated by the tenant. password admin.password string Tenant/Enterprise password. The same password is used for authentication in all the subsequent API's initiated by the tenant. domain domain string Domain of the Tenant/Enterprise. Unique attribute to identify the tenant and subscribers associated with the tenant. This is concatenated to the Enterpriser's username and subscriber's username to generate the user ID used for authenticating the API request. Optional Fields Variable Type Description name admin.name string Name of Tenant/Enterprise. The value is used for information purpose. admin.admin string address of Tenant/Enterprise. The value is used for information purpose. apn apn List<string> List of APNs associated with the tenant. published_apis published_apis Set<api> List of published APIs for tenant. 11

12 Tenants Mandatory Fields Variable Type Description api_name published_apis.api_name string Name of the API being published. This is a mandatory field in optional published_apis field. api_version published_apis.api_version float Version of the API being published. This is a mandatory field in optional published_apis field. 12

13 Subscribers Subscribers Subscribers are API users that super tenants, tenants, and enterprise administrators can create. Subscribers are API users with restrictive access. Subscribers can access/modify only their account and subscribe to APIs. A subscriber is identified from the username passed as part of the authentication parameter. The authentication parameter should be of the type username@domain, where username is subscriber's username and domain is the domain provisioned for the subscriber's tenant. Onboarding Subscriber Methods The following table describes the Onboarding API operations and their respective methods: API Request URL HTTP Method Access Level Create /onboarding/subscriber POST Super Tenant Enterprise Update /onboarding/subscriber PUT Super Tenant Enterprise Subscriber Delete /onboarding/subscriber DELETE Super Tenant Enterprise Detail /onboarding/subscriber GET Super Tenant Enterprise Subscriber List /onboarding/subscriber/list GET Super Tenant Enterprise Onboarding Subscriber Request Fields The following tables describe the fields used in the JSON payload of the Onboarding Subscriber API request: 13

14 Subscribers Mandatory Fields Variable Type Description username username string Unique username of the Subscriber. The same along with enterpriser' s domain is used for authentication in all the subsequent API s initiated by the subscriber. password password string Password of the subscriber to be used for authentication. Optional Fields Variable Type Description name name string Name of the subscriber. The value is used for information purpose. subscribed_apis subscribed_apis Set<api> List of subscribed APIs for subscriber. api_name subscribed_apis.api_name string Name of the API being subscribed. This is a mandatory field in optional subscribed_apis field. api_version subscribed_apis.api_version float Version of the API being subscribed. This is a mandatory field in optional subscribed_apis field. User Privileges for APIs Users can publish or subscribe to APIs. 14

15 Publishing APIs Publishing APIs Tenants, super tenants, and enterprise administrators can perform the following functions. View the list of supported APIs using the GET method with the following URL: Publish APIs for the subscribers to use along with the API version with the published_apis field using the POST method. The subscribers can then subscribe to and use the APIs. Super tenants have complete publishing privileges. As tenants and enterprise administrators, you have the following privileges: You can publish only supported APIs. You cannot unpublish an API that has subscriptions. All subscribers must unsubscribe from the API, if you want to unpublish an API. You can publish APIs during Update Tenant (which you, as a tenant, can do also) operations. A super tenant can publish APIs during an Add Tenant operation. You can associate any version with the API during publishing using the api_version field. You must specify this field when publishing an API. 15

16 Subscribing to APIs Subscribing to APIs As a subscriber, you can subscribe to APIs that are published by your tenant. You can use the subscribed_apis field with POST method to subscribe to the APIs. Alternatively, the tenant (or super tenant) can subscribe you to an API when adding you as a subscriber. Both the API name and version are required when subscribing to an API. 16

17 /onboarding/tenant /onboarding/tenant POST URL: /onboarding/tenant Description: Creates a new Tenant Security Schemes: Base64 Basic Authentication: Super Tenant Admin credentials Request Body Type: application/json Schema "description": "Tenant Onboarding record", "type": "object", "properties": "domain":, "admin": "description" : "Tenant admin details", "type": "object", "properties": "username":, "password":, "name":, " ":,, "required" : ["username", "password"], "apn": "type": "array[string]" "subscribers": "type": "array[object]" "published_apis": "type": "array[object]", "required": ["domain"] Example: "domain" : "enterprise3.com", "admin" : "username": "enterprise3", "password": "password", "name": "Enterprise3", 17

18 /onboarding/tenant Response " ": "apn" : [ "apn-131"], published_apis : [ api_name : UpdateQoS, api_version : 1.0 ] HTTP status code: 200 Body Type: application/json Schema: "description": "Tenant onboarding response", "type": "object", "properties": "code":, "message":, "action":, "result": "type": object", "request": "type": object",, "required": ["code", "message", "action"] Example: "action": "add", "code": "0", "message": "Record added successfully", "result": "domain": "enterprise3.com", "admin": "username": "enterprise3", " ": " @enterprise3.com", "name": "Enterprise3", "apn": [ "apn-131" ], published_apis : [ api_name : UpdateQoS, api_version : 1.0 ] 18

19 /onboarding/tenant HTTP status code: 401 Body Type: application/json Example: "action": "add", "code": "E404", "message": "Invalid username/password. Authentication Failed.", "request": "domain": "enterprise3.com", "admin": "username": "enterprise3", " ": "name": "Enterprise3", "apn": [ "apn-131" ] Curl Example Note: Depending on Unix/Linux shell, there are some limitations with CURL commands when using special characters in usernames and passwords for creating tenants and subscribers. Avoid using $,!, :, " and \ special characters for the usernames or passwords when creating tenants and subscribers. Command to create tenant: curl -k -H "Content-Type: application/json" -X POST --data "@tenant.json" Curl response: "action":"add","code":"0","message":"record added successfully","result":"domain":"enterprise.com","admin":"username":"admin"," ":"ad min@enterprise.com","name":"enterprise corporation","apn":["apn-11","apn- 13"],"published_apis":["api_name":"UpdateQoS","api_version":1.0] Sample tenant.json "domain" : "enterprise.com", "admin" : "username" : "admin", "password" : "password", 19

20 /onboarding/tenant " " : "admin@enterprise.com", "name" : "enterprise corporation", "apn" : [ "apn-11","apn-13" ], "published_apis" : [ "api_name" : "UpdateQoS", "api_version" : 1.0 ] GET Request Response URL: /onboarding/tenant Description: Query Tenant Security Schemes: Base64 Basic Authentication: Onboarding credentials of tenant administrator or super tenant Query Parameters: domain: (string) Domain name of the Tenant. Required in case super tenant credentials are used HTTP status code: 200 Body Type: application/json Schema: "description": "Tenant onboarding response", "type": "object", "properties": "code":, "message":, "action":, "result": "type": object", "request": "type": object",, "required": ["code", "message", "action"] Example: 20

21 /onboarding/tenant "action": "details", "code": "0", "message": "1 record found", "result": "domain": "enterprise3.com", "admin": "username": "enterprise3", " ": "name": "Enterprise3", "apn": [ "apn-131" ], published_apis : [ api_name : UpdateQoS, api_version : 1.0 ] Curl Example Command to view tenant with super tenant credentials: curl -k -H "Content-Type: application/json" -X GET om Curl response: "action":"details","code":"0","message":"1 record found","result":"domain":"enterprise.com","admin":"username":"admin"," ":"admin@ent erprise.com","name":"enterprise corporation","apn":["apn-11","apn- 13"],"subscribers":["username":"subscriber","name":"Subscriber","subscribed_apis":["api _name":"updateqos","api_version":1.0]],"published_apis":["api_name":"updateqos","api_v ersion":1.0] Command to view tenant details with tenant credentials: curl -k -H "Content-Type: application/json" -X GET -u "admin@enterprise.com:password" :6443/api/onboarding/tenant Curl response: "action":"details","code":"0","message":"1 record found","result":"domain":"enterprise.com","admin":"username":"admin"," ":"admin@ent erprise.com","name":"enterprise corporation","apn":["apn-11","apn- 13"],"subscribers":["username":"subscriber","name":"Subscriber","subscribed_apis":["api _name":"updateqos","api_version":1.0]],"published_apis":["api_name":"updateqos","api_v ersion":1.0] 21

22 /onboarding/tenant PUT Request URL: /onboarding/tenant Description: Update Tenant Security Schemes: Base64 Basic Authentication: Onboarding credentials of tenant administrator or super tenant Query Parameters: Body domain: (string) Domain name of the Tenant. Required in case super tenant credentials are used Type: application/json Schema: "type": "object", "properties": "admin": "type": "object", "properties": "username":, "password":, "name":, " ":, "required": [ "username" ], "apn": "type": "array", "items": [ 22

23 /onboarding/tenant ], "published_apis": "type":"array", "items":[ "type":"object", "properties": "api_name":, "api_version": ] Response HTTP status code: 200 Body Type: application/json Schema: "type": "object", "properties": "action":, "code":, "message":, "result": "type": "object", "properties": "domain":, "admin": "type": "object", "properties": 23

24 /onboarding/tenant "username":, " ":, "name":, "subscribers": "type": "array", "items": "type": "object", "properties": "username":, "name":, "subscribed_apis": "type": "array", "items": "type": "object", "properties": "api_name":, "api_version": "type": "integer", "published_apis": "type": "array", "items": "type": "object", "properties": "api_name":, "api_version": "type": "integer" 24

25 /onboarding/tenant, "required": [ "action", "code", "message", "result" ] Example: "action": "update", "code": "0", "message": "1 record found", "result": "domain": "enterprise3.com", "admin": "username": "enterprise3", " ": " @enterprise3.com", "name": "Enterprise3", "subscribers": [ "username": "subscriber1", "name": "subscriber1" ], "published_apis": [ "api_name": "UpdateQos", "api_version": 1 ] 25

26 /onboarding/tenant Curl Example Note: Depending on Unix/Linux shell, there are some limitations with CURL commands when using special characters in usernames and passwords for creating tenants and subscribers. Avoid using $,!, :, " and \ special characters for the usernames or passwords when creating tenants and subscribers. Command for tenant update: curl -k -H "Content-Type: application/json" -X PUT om --data "@tenant.json" Curl response: "action":"update","code":"0","message":"record updated successfully","result":"domain":"enterprise.com","admin":"username":"admin"," ":"ad min@enterprise.com","name":"enterprise corporation","apn":["apn-11","apn- 13"],"subscribers":["username":"subscriber","name":"Subscriber","subscribed_apis":["api _name":"updateqos","api_version":1.0]],"published_apis":["api_name":"updateqos","api_v ersion":1.0] DELETE URL: /onboarding/tenant Description: Delete Tenant Security Schemes: Base64 Basic Authentication: Super Tenant Admin credentials Request Response Query Parameters: domain: required (string) Domain name of the Tenant. HTTP status code: 200 Body Type: application/json Schema: "type": "object", "properties": "action":, 26

27 /onboarding/tenant "code":, "message":, "result": "type": "object", "properties": "domain":, "admin": "type": "object", "properties": "username":," ":, "name":, "subscribers": "type": "array", "items": "type": "object", "properties": "username":, "name":, "subscribed_apis": "type": "array", "items": "type": "object", "properties": "api_name":, "api_version": "type": "integer" 27

28 /onboarding/tenant, "published_apis": "type": "array", "items": "type": "object", "properties": "api_name":, "api_version": "type": "integer", "required": [ "action", "code", "message", "result" ] Example: "action": "delete", "code": "0", "message": "Record deleted successfully", "result": "domain": "enterprise3.com", "admin": "username": "enterprise3", " ": " @enterprise3.com", "name": "Enterprise3", "subscribers": [ "username": "subscriber1", "name": "subscriber1" ], "published_apis": [ 28

29 /onboarding/tenant "api_name": "UpdateQos", "api_version": 1 ] Curl Example Command to delete tenant: curl -k -H "Content-Type: application/json" -X DELETE om Curl response: "action":"delete","code":"0","message":"record deleted successfully","result":"domain":"enterprise.com","admin":"username":"admin"," ":"ad min@enterprise.com","name":"enterprise corporation","apn":["apn-11","apn- 13"],"published_apis":["api_name":"UpdateQoS","api_version":1.0] 29

30 /onboarding/tenant/list /onboarding/tenant/list GET URL: /onboarding/tenant/list Description: Security Schemes: Base64 Basic Authentication: Super Tenant Admin credentials Response HTTP status code 200 Body Type: application/json Example: "action": "list", "code": "0", "message": "1 record(s) found", "result": [ "domain": "enterprise3.com", "admin": "username": "enterprise3", " ": " @enterprise3.com", "name": "Enterprise3", "apn": [ "apn-131" ], published_apis : [ api_name : UpdateQoS, api_version : 1.0 ] ] 30

31 /onboarding/tenant/list Curl Example Command to view list of tenants: curl -k -H "Content-Type: application/json" -X GET Curl response: "action":"list","code":"0","message":"1 record(s) terprise.com","name":"enterprise corporation","apn":["apn-11","apn- 13"],"published_apis":["api_name":"UpdateQoS","api_version":1.0]] 31

32 /onboarding/subscriber /onboarding/subscriber POST Request URL: /onboarding/subscriber Description: Creates a new Subscriber Security Schemes: Base64 Basic Authentication: Onboarding credentials of tenant administrator or super tenant Query Parameters: domain: (string) Domain name of the Tenant. Required in case super tenant credentials are used Body Type: application/json Schema: "type": "object", "properties": "username":, "password":, "name":, "subscribed_apis": "type": "array", "items": "type": "object", "properties": "api_name":, "api_version": 32

33 /onboarding/subscriber, "required": [ "username", "password" ] Example: "username":"subscriber1", "password":"password", "name":"subscriber1", "subscribed_apis":[ "api_name":"updateqos", "api_version":"1.0" ] Response HTTP status code: 200 Body Type: application/json Schema: "type": "object", "properties": "action":, "code":, "message":, "result": "type": "object", "properties": "username":,"name": 33

34 /onboarding/subscriber, "subscribed_apis": "type": "array", "items": "type": "object", "properties": "api_name":, "api_version": "type": "integer", "required": [ "action", "code", "message", "result" ] Example: "action": "add", "code": "0", "message": "Record added successfully", "result": "username": "subscriber2", "name": "subscriber1", "subscribed_apis": [ "api_name": "UpdateQoS", "api_version": 1 ] 34

35 /onboarding/subscriber Curl Example Note: Depending on Unix/Linux shell, there are some limitations with CURL commands when using special characters in usernames and passwords for creating tenants and subscribers. Avoid using $,!, :, " and \ special characters for the usernames or passwords when creating tenants and subscribers. Command to create subscriber with super tenant credentials: curl -k -H "Content-Type: application/json" -X POST se.com --data "@subscriber.json" Curl response: "action":"add","code":"0","message":"record added successfully","result":"username":"subscriber","name":"subscriber","subscribed_apis":[" api_name":"updateqos","api_version":1.0] Command to create subscriber with tenant credentials: curl -k -H "Content-Type: application/json" -X POST -u "admin@enterprise.com:password" --data "@subscriber.json" Curl response: "action":"add","code":"0","message":"record added successfully","result":"username":"subscriber","name":"subscriber","subscribed_apis":[" api_name":"updateqos","api_version":1.0] Sample subscriber.json "username" : "subscriber", "password": "password", "name": "Subscriber", "subscribed_apis": [ "api_name" : "UpdateQoS", "api_version" : 1.0 ] ] GET URL: /onboarding/subscriber Description: Query Subscriber Security Schemes: Base64 Basic Authentication: Onboarding credentials of subscriber or tenant administrator or super tenant administrator. Request Query Parameters: 35

36 /onboarding/subscriber domain: (string) Domain name of the Tenant. Required if the super tenant credentials are used username: (string) Subscriber's username field. Required if tenant admin or super tenant credentials are used Response HTTP status code: 200 Body Type: application/json Schema: "type": "object", "properties": "action":, "code":, "message":, "result": "type": "object", "properties": "username":, "name":, "subscribed_apis": "type": "array", "items": "type": "object", "properties": "api_name":, "api_version": "type": "integer" 36

37 /onboarding/subscriber, "required": [ "action", "code", "message", "result" ] Example: "action": "details", "code": "0", "message": "1 record found", "result": "username": "subscriber2", "name": "subscriber1", "subscribed_apis": [ "api_name": "UpdateQoS", "api_version": 1 ] HTTP status code: 400 Description: Body With tenant admin credentials when username is not provided. With super tenant credentials when both the query parameters are not provided. Type: application/json Example: "action": "details", "code": "E401", "message": "Mandatory parameter [username] missing in request" 37

38 /onboarding/subscriber Curl Example Command to view subscriber details: curl -k -H "Content-Type: application/json" -X GET -u :6443/api/onboarding/subscriber?username=subscriber Curl response: "action":"details","code":"0","message":"1 record found","result":"username":"subscriber","name":"subscriber","subscribed_apis":["api_nam e":"updateqos","api_version":1.0] PUT Request URL: /onboarding/subscriber Description: Update Subscriber Security Schemes: Base64 Basic Authentication: Onboarding credentials of subscriber or tenant administrator or super tenant administrator. Query Parameters: Body domain: (string) Domain name of the Tenant. Required if the super tenant credentials are used username: (string) Subscriber's username field value. Required if super tenant or tenant admin credentials are used Type: application/json Schema: "type": "object", "properties": "password":, "name":, "subscribed_apis": "type": "array", "items": "type": "object", "properties": 38

39 /onboarding/subscriber "api_name":, "api_version": Response HTTP status code: 200 Body Type: application/json Example: "action": "update", "code": "0", "message": "subscriber1 updated successfully", "result": "username": "subscriber1", "name": "subscriber_newname" HTTP status code: 401 Body Type: application/json Example: "action": "update", "code": "E404", "message": "Invalid username/password. Authentication Failed.", "request": "name": "subscriber_newname" 39

40 /onboarding/subscriber HTTP status code: 404 Body Type: application/json Example: "action": "update", "code": "E402", "message": "Subscriber subscriber3 does not exist.", "request": "name": "subscriber_newname" Curl Example Note: Depending on Unix/Linux shell, there are some limitations with CURL commands when using special characters in usernames and passwords for creating tenants and subscribers. Avoid using $,!, :, " and \ special characters for the usernames or passwords when creating tenants and subscribers. Command to update subscriber: curl -k -H "Content-Type: application/json" -X PUT -u "admin@enterprise.com:password" --data "@subscriber.json" Curl response: "action":"update","code":"0","message":"subscriber updated successfully","result":"username":"subscriber","name":"subscriber","subscribed_apis":[" api_name":"updateqos","api_version":1.0] Command to update subscriber without query parameter: curl -k -H "Content-Type: application/json" -X PUT -u "admin@enterprise.com:password" --data "@subscriber.json" Curl Response: "action":"update","code":"e401","message":"mandatory parameter [username] missing in request","request":"username":"subscriber","name":"subscriber","subscribed_apis":["api_ name":"updateqos","api_version":1.0] 40

41 /onboarding/subscriber DELETE URL: /onboarding/subscriber Description: Delete Subscriber Security Schemes: Base64 Basic Authentication: Onboarding credentials of tenant administrator or super tenant Request Query Parameters: domain: (string) Domain name of the Tenant. Required if the super tenant credentials are used username: required (string) Subscriber's username field value. Response HTTP status code: 200 Body Type: application/json Example: "action": "delete", "code": "0", "message": "Record deleted successfully", "result": "username": "subscriber2", "name": "subscriber1", "subscribed_apis": [ "api_name": "UpdateQoS", "api_version": 1 ] 41

42 /onboarding/subscriber HTTP status code: 404 Body Type: application/json Example: "action": "delete", "code": "E402", "message": "Subscriber subscriber2 does not exist." Curl Example Command to delete subscriber with super tenant credentials: curl -k -H "Content-Type: application/json" -X DELETE se.com\&username=subscriber Curl response: "action":"delete","code":"0","message":"record deleted successfully","result":"username":"subscriber","name":"subscriber","subscribed_apis":[" api_name":"updateqos","api_version":1.0] Command to delete subscriber with tenant credentials: curl -k -H "Content-Type: application/json" -X DELETE -u Curl response: "action":"delete","code":"0","message":"record deleted successfully","result":"username":"subscriber","name":"subscriber","subscribed_apis":[" api_name":"updateqos","api_version":1.0] 42

43 /onboarding/subscriber/list /onboarding/subscriber/list GET URL: /onboarding/subscriber/list Description: Security Schemes: Base64 Basic Authentication: Onboarding credentials of tenant administrator or super tenant Request Response Query Parameters: domain: (string) Domain name of the Tenant. Required if the super tenant credentials are used HTTP status code: 200 Body Type: application/json Schema: "type": "object", "properties": "action":, "code":, "message":, "result": "type": "array", "items": [ "type": "object", "properties": "username":, "name": 43

44 /onboarding/subscriber/list, "type": "object", "properties": "username":, "password":, "name":, "subscribed_apis": "type": "array", "items": "type": "object", "properties": "api_name":, "api_version": "type": "integer" ], "required": [ "action", "code", "message", "result" ] Example: "action": "list", "code": "0", "message": "2 record(s) found", 44

45 /onboarding/subscriber/list "result": [ "username": "subscriber1", "password": "password", "name": "subscriber1", "username": "subscriber2", "password": "password", "name": "subscriber1", "subscribed_apis": [ "api_name": "UpdateQoS", "api_version": 1 ] ] Curl Example Command to list subscribers: curl -k -H "Content-Type: application/json" -X GET -u "admin@enterprise.com:password" Curl response: "action":"list","code":"0","message":"1 record(s) found","result":["username":"subscriber","name":"subscriber","subscribed_apis":["api_na me":"updateqos","api_version":1.0]] 45

46 /onboarding/api/list /onboarding/api/list GET URL: /onboarding/api/list Description: Retrieves the list of APIs supported by MOG. Only these APIs can be published and subscribed. Security Schemes: Base64 Basic Authentication: Onboarding credentials of subscriber or tenant administrator or super tenant administrator. Response HTTP status code 200 Body Type: application/json Schema: "type": "array", "items": "type": "object", "properties": "api_name":,, "required": [ "api_name", ] Example: [ ] "api_name": "UpdateQoS" Curl Example Command to view API List with supertenant credentials: 46

47 /onboarding/api/list curl -k -H "Content-Type: application/json" -X GET Curl Response: ["UpdateQoS"] Command to view API List with tenant credentials: curl -k -H "Content-Type: application/json" -X GET -u Curl Response: ["UpdateQoS"] Command to view API List with subscriber credentials: curl -k -H "Content-Type: application/json" -X GET -u Curl Response: ["UpdateQoS"] 47

48 Chapter 4 Authentication API This chapter includes the following topics: Authentication Token Overview /auth/token 48

49 Authentication Token Overview Authentication Token Overview The MOG APIs supports token based "Bearer" authentication. Each token can be used by multiple clients and clients can have several valid tokens. You use the Authentication API to generate the token with the onboarding credentials. The response contains details of the type of the token and the token expiry in seconds. You can regenerate new authorization tokens by sending a new request; the response includes a new token with a new token expiry. The token expiry of the original token does not change. Token Generation Use the onboarding credentials to request for an authentication token. Send a POST method to the following URI: The response contains details such as the token, token type, and the token expiry in seconds. Token Usage Use the generated token as part of the Authorization header when accessing subscribed APIs. Token Expiry Use the GET method to check the token expiry. Use the following URL: The API request must include the "Authorization" header with the "Bearer" token generated by using the POST method. A successful response includes the "token", "token_type" and "expires_in" parameters with 200 (OK) status code. Token Regeneration You can generate a new token using the existing token which is valid and did not expire. Use the following URL: Use the PUT method with the API request. The request must include the existing authentication token as string with value "Bearer token string in the authorization header. 49

50 /auth/token /auth/token POST URL: /auth/token Description: Generates new authentication token Security Schemes: Base64 Basic Authentication: Subscriber credentials Response HTTP status code: 200 Body Type: application/json JSON Schema: "type": "object", "properties": "code": "description": "HTTP Status Code", "type": "Integer", "token": "description": "Token value", "type": "String", "type": "description": "Type of the token. Value is Bearer", "type": "String", "expires_in": "description": "Token validity time in seconds", "type": "String" Curl Example Command to generate authentication token: curl -k -H "Content-Type: application/json" -u -X POST 50

51 /auth/token Curl response: "code":200,"token":"xri8khupwqx4bpphyarpmis5szjyn3z92wet2yvvgjjc0q1sqyb6jvyf1gdvk5jl4gkq kcau/zl4igrh5ovvsv7cvq07jllcs7xrg8hqss70tlb1nx9gwev2epy7gb2llamup8y5tod9sqopc/xsiw==","to ken_type":"bearer","expires_in":"86399" GET Response URL: /auth/token Description: View details about authentication token Security Schemes: Bearer Headers Authorization Authorization Header has the token as string with value "Bearer token string" HTTP status code: 200 Body Type: application/json JSON Schema: "type": "object", "properties": "code": "description": "HTTP Status Code", "type": "Integer", "token": "description": "Token value", "type": "String", "type": "description": "Type of the token. Value is Bearer", "type": "String", "expires_in": "description": "Token validity time in seconds", "type": "String" 51

52 /auth/token Curl Example Command to view authentication token details: curl -k -H "Content-Type: application/json" -H "Authorization: Bearer xri8khupwqx4bpphyarpmis5szjyn3z92wet2yvvgjjc0q1sqyb6jvyf1gdvk5jl4gkqkcau/zl4igrh5ovvsv7cv q07jllcs7xrg8hqss70tlb1nx9gwev2epy7gb2llamup8y5tod9sqopc/xsiw==" -X GET :6443/api/auth/token Curl response: "code":200,"token":"xri8khupwqx4bpphyarpmis5szjyn3z92wet2yvvgjjc0q1sqyb6jvyf1gdvk5jl4gkq kcau/zl4igrh5ovvsv7cvq07jllcs7xrg8hqss70tlb1nx9gwev2epy7gb2llamup8y5tod9sqopc/xsiw==","to ken_type":"bearer","expires_in":"78930" PUT URL: /auth/token Description: Regenerate token using existing authentication token which is valid and did not expire. Security Schemes: Bearer Headers Authorization Header has the token as string with value "Bearer token string" Response HTTP status code: 200 Body Type: application/json JSON Schema: "type": "object", "properties": "code": "description": "HTTP Status Code", "type": "Integer", "token": "description": "Token value", "type": "String", "type": "description": "Type of the token. Value is Bearer", "type": "String", "expires_in": "description": "Token validity time in seconds", "type": "String" 52

53 /auth/token Curl example: curl -k -H "Content-Type: application/json" -H "Authorization: Bearer NCdxDxj7cfEE5I746b0TNqULByj7TvELrc9LCywiskk8YVHCMFzSPRlN74BJi2qLuE774URtY9eBJvlBDP7lBPdyL 8h84pfpnGwQypG0gHRTvhQZJWCLXUklgdbQAXPdRYoPC2QhY+PkcdMA6XwLHw==" -X PUT Response: "code":200,"token":"nrhkx57gjnltv+kevfizyqulbyj7tvelrc9lcywiskk8yvhcmfzsprln74bji2qlue77 4URtY9eBJvlBDP7lBPdyL8h84pfpnGwQypG0gHRTvhQZJWCLXUklgdbQAXPdRYoPC2QhY+PkcdMA6XwLHw==","to ken_type":"bearer","expires_in":"86399" 53

54 Chapter 5 UpdateQoS You can use the Update QoS API to enhance the QoS of a subscriber dynamically. You can perform the following QoS operations with the Update QoS API: Modify default bearer QoS Modify dedicated bearer QoS Modify sponsored data Note: Based on the token that is used in the payload, the tenant and the corresponding onboarding user are identified. URI The URI of the northbound API is specified in the following format: Where: api_path: REST API that is requested. The api_path of the QoS API is /network/define/qostype. version: Version of the published / subscribed REST API. Session Identifier In case of PUT, DELETE and GET methods for operation on unique session, additionally session identifier needs to be appended to the URI: identifier> 54

55 Update QoS Sessions and Methods Update QoS Sessions and Methods Update QoS API supports dynamic changes to the subscriber QoS, bandwidth, and sponsored data. Each API session includes a request, synchronous response, and a callback. Each request uses a specific HTTP method. The following table describes the Update QoS sessions and the respective methods: For the following sessions: Create API session for Update QoS Update an existing session Delete an existing session Read details of an existing session Use the following method POST PUT DELETE GET The following section describes each of the sessions: Session Creation Session Update Session Delete Session Read A unique session identifier is associated with each session. If multiple APNs exist, then a session is created for each APN. Use the PUT method to update an existing session. Append the session identifier at the end of the URL. The DELETE method is used to delete an existing session. You must append the session identifier at the end of the URI. Note: A session deletion can also be triggered by MOG when the duration of the QoS definition, as specified in the create/update request, of the session completes. The GET method is used to query sessions in the MOG system. You must append the unique session identifier at the end of the URI. You can query for a list of sessions using the base URI and providing the following one or both of the query parameters: address as defined in the create request table apn as defined in the create request table. You can also specify token for the callback as defined in the create request table. Update QoS Submission Response On receiving the API request, MOG validates the JSON syntax. If the syntax is valid, MOG submits the API request and responds with a 200 (OK) status code. If the validation fails, then a 400 (BAD REQUEST) status code is sent immediately with a JSON describing the reason for failure. 55

56 Update QoS Sessions and Methods If the api_path of the URI does not match the supported API paths, then a 404 (NOT FOUND) status code is sent. 56

57 Update QoS Request Fields Update QoS Request Fields The following tables describe the mandatory and optional fields used in the JSON payload of the Update QoS API request: Mandatory Fields Variable Type Description address msisdn-var imsi-var ipv4 ipv6 acr-string string Subscriber address in any one of the following formats: E164 encoded MSISDN: "address":"tel:+<msisdn>" IMSI: "address":"imsi:<imsi>" IPv4: "address":"ipv4:<ipv4-dotted-quad>" IPv6: "address":"ipv6:<ipv6-address> Acr: address:acr:<acr value> Optional Fields Variable Type Descriptions qci qci-var uint8 QoS Class Indicator with a range of 1 to 9. If not specified in JSON, the value is picked from the use case template of Policy Builder. QCI of 1 to 4 is used for guaranteed bit rates. The QCI value is Mapped to Media Type before sending to PCRF. The Media-Type AVP is used by the PCRF to derive the QCI. The AVP values can be found in 3GPP TS The following QCI values describe the mapping of QCI to Media-Type: QCI of 1 indicates Media-Type of Audio QCI of 2 indicates Media-Type of Video QCI of 3 or 4 indicates Media Type of Application QCI of 5 indicates Media Type of Control QCI of 6, 7, 8 indicates Media Type of Data QCI of 9 indicates Media Type of Other For a default bearer, the QCI values indicate: QCI 1 and 2 indicates Conversational QCI 3 and 4 indicates Streaming QCI 5,6,7, and 8 indicates Interactive QCI 9 indicates Background 57

58 Update QoS Request Fields Mandatory Fields Variable Type Description maxbitrate maxbitrate-var object Maximum bit rate in Kbps for uplink and downlink. If this field is not supplied, the value configured in Service Configuration of the API will be used. uplink uplink-var uint64 Upload rate in Kbps. downlink downlink-var uint64 Download rate in Kbps. flows flows-var string Flows to be applied on the bearer. Multiple flows are included as objects in the array. Each object will have following fields: srcaddress srcport srcportlist srcportranges destaddress destport destportlist destportranges protocol srcaddress src-ip-address-var string IPv4 or IPv6 address of user equipment (UE). srcport src-port-var string IP port of UE. srcportlist src-port-list-var string IP port list of UE. srcportranges src-port-ranges-var string IP port ranges of UE. destaddress dest-ip-address-var string IPv4 or IPv6 address of app server. This field is mandatory for each flow entry. destport dest-port-var string IP port of application server. destportlist dest-port-list-var string IP port list of application server. destportranges dest-port-ranges-var string IP port ranges of application server. protocol protocol-var uint32 Transport protocol number (as per IANA) used by application 58

59 Update QoS Request Fields Mandatory Fields Variable Type Description duration duration-var uint32 Duration in seconds of QoS definition for the enduser subscriber. When duration is specified, the session is terminated on the completion of the duration value. If duration is not provided, the session will last till an explicit DELETE is issued. volume volume-var uint64 Maximum amount of data in bytes for which the QoS change should be maintained. sponsorid sponsor-id-var string The name of the sponsor for the QoS change. If this field is supplied, the sponsor organization will be associated with the QoS change (also for billing purposes). apn apn-var string APN associated for the request. If not supplied, the value is considered from the onboarding database. The onboarding database supports maximum of 5 APNs. An API request without APN field results in QoS updates for all the configured APNs in the onboarding database. If the subscriber address is in ACR format, APN information is part of the ACR address. callback callback-var string A URI for receiving status updates. If this field is supplied, the specified URI will be called when the status of the requested QoS session changes. If not supplied, callback value is considered from the configuration. Both http and https are supported in callback URI. uri uri-var uint8 A uniform resource identifier string. token token-var string A token string, not to be interpreted by the server but returned to the caller in responses. arp arp-var Object If supplied, indicates the Priority of Allocation and Retention for the corresponding APN configuration of the default/dedicated bearer. 59

60 Update QoS Request Fields Mandatory Fields Variable Type Description priority priority-var uint8 Used to decide whether a bearer establishment or modification request can be accepted or needs to be rejected, in case of resource limitations. Priority is also used to decide which existing bearers may be pre-empted during resource limitations. The priority level defines the relative importance of a resource request and takes a range of values from 1 to 15 with 1 as the highest level of priority. The AVP details can be found in 3GPP TS preemptioncapability pre-emption-capability-var boolean Determines whether a bearer can use resources from another bearer with a lower priority and is usually set for emergency services. preemptionvulnerability pre-emption-vulnerabilityvar boolean Determines whether a bearer can give up resources to a bearer with a higher priority. intent Intent-var Object Indicates the Intention and Priority for the QoS. You can assign the following Intention values to modify the bandwidth: BOOST: Increases the QoS (QCI, ARP, Bandwidth) of the subscriber. Cisco Policy Suite selects the higher value of the applied vs. requested QoS. THROTTLE: Decreases the QoS (QCI, ARP, Bandwidth) of the subscriber. Cisco Policy Suite selects the lower value of the applied vs. requested QoS. REFRESH : Refreshes the CC-Time of the session with configured duration value from create session or validity time configured for the tenant and sponsor ID pair in Policy Builder MOG Configuration plugin. Note: Not case sensitive You can also assign the Priority of an Intention (positive integer). When multiple Rx sessions exist, Cisco Policy Suite decides whether to apply Intention or not by comparing the priority value. A higher value means lowest priority. 60

61 Update QoS Request Fields Mandatory Fields Variable Type Description dpcc dpcc-var Object Dynamic PCC includes two attributes: name and value. Both name and value of DPCC are used to evaluate CRD table to get PCC rule. starttime Starttime-var Object Which takes year, month, day, hour, minutes and seconds. This starttime indicates session starttime. 61