All rights reserved. No part of this publication may be reproduced, distributed, or transmitted in any form or by any means, including photocopying, recording, or other electronic or mechanical methods, without the prior written permission of the publisher, except in the case of brief quotations embodied in critical reviews and certain other noncommercial uses permitted by copyright law. For permission requests, write to the publisher, addressed “Attention: Permissions Coordinator,” at the address below.
This specification defines the FIWARE-OFNIC v1 REST ful API. Such API exposes network status information and it enables a certain level of programmability within the network.
This is a work in progress and is changing on a daily basis. First major release 4 will be released by the end of September 2015
This specification is licensed under the FIWARE Open Specification License.
The NetIC Restful API API is intended to access network status information and to allow a pre-defined level of programmability within the network. This programmability may also enable network virtualization, i. e., the abstraction of the physical network resources as well as their control by a virtual network provider. This is a RESTful, resource-oriented API accessed via HTTP that uses JSON-based representations for information interchange. It should be noted that the exposition of specific capabilities via the northbound interface depends on the capabilities and the technology of the underlying network. Users of the API will be able to explore the functionalities, by navigating this API in a RESTful fashion.
OK - the request was successful (some API calls may return 201 instead). Created - the request was successful and a resource was created. No Content - the request was successful but there is no representation to return (i.e. the response is empty). Bad Request - the request could not be understood or was missing required parameters. Unauthorized - authentication failed or user doesn't have permissions for requested operation. Forbidden - access denied. Not Found - resource was not found. Method Not Allowed - requested method is not supported for resource. Each HTTP request against the NetIC RESTful API requires the inclusion of specific authentication credentials. The specific implementation of this API may support multiple authentication schemes (OAuth, Basic Auth, Token) and will be determined by the specific provider that implements the GE. Please contact with it to determine the best way to authenticate against this API. Remember that some authentication schemes may require that the API operate using SSL over HTTP (HTTPS).
This API exposes a set of commands on the NetIC GE that enables information retrieval from and some level of control of the underlying network. This is done through manipulating different objects, like:
In this section we go in depth for each operation. The API operations are divided into three groups of functionalities:
The next subsections will provide an insight of all the possible commands of each group.
Synchronize commands allow the users of the NetIC API to retrieve information about network topology, node configuration, port status, etc.
Retrieve information about the node with id: nodeID
Retrieve all available information about the port with id: nodeID located in the node with id: portID
nodeID (string) - OpenFlow Node ID
portID (string) - OpenFlow Node port's number
List all created virtual paths in the network.
Create a new virtual path in the network.
nw_src (String | required) - IPv4 first node addresses
nw_dst (String | required) - IPv4 last node addresses
dp_src (String | optional) - first node ID (OpenFlow ID) - Mandatory if hosts don't announce their link layer info with LLDP
dp_dst (String | optional) - last node ID (OpenFlow ID) - Mandatory parameter Mandatory if hosts don't announcetheir link layer info with LLDP
dl_src (String | optional) - first node mac address - Mandatory if hosts don't announce their link layer info with LLDP
dl_dst (String | optional) - last node mac address - Mandatory if hosts don't announce their link layer info with LLDP
tp_src (String | optional) - first node tcp/udp port - Optional
tp_dst (String | optional) - last node tcp/udp port - Optional
bandwidth (String | optional) - bandwidth on path (kbps) - Optional
bidirectional (String | required) - bidirectional flows
first_port (String | optional) - ingress port on first node - Mandatory if hosts don't announce their link layer info with LLDP
last_port (String | optional) - exit port on last node - Mandatory if hosts don't announce their link layer info with LLDP
etherType (String | optional) - etherType content - Optional
protocol (String | optional) - protocol content - Optional
{
"nw_src":"10.0.0.1",
"nw_dst":"10.0.0.3",
"dp_src":"",
"dp_dst":"",
"dl_src":"",
"dl_dst":"",
"tp_src":"",
"tp_dst":"",
"bandwidth":"",
"bidirectional":"1",
"first_port":"",
"last_port":"",
"etherType":"",
"protocol":""
}
List all created virtual paths in the network.
Remove a virtual path
Monitor group of commands provides the APIs to retrieve collected network statistics about ports of network nodes. Parameters collected are amount of bytes transmitted per unit of time, number of packets transmitted per unit of time and others. The Monitor commands are explained below.
Retrieve all available statistics about port with id: portID on node with id: nodeID
nodeID (String) = OpenFlow node ID
portID (String) = OpenFlow node's port number
Retrieve all available statistics about the virtual path with id: pathID
Headers
Content-Type: application/jsonBody
[
{
"paths":[],
"nodes":[
"00:00:00:00:00:00:00:02",
"00:00:00:00:00:00:00:01",
"00:00:00:00:00:00:00:03"
]
}
]
Headers
Content-Type: application/jsonBody
[
{
"id":"2",
"type":"OF"
},
{
"id":"1",
"type":"OF"
},
{
"id":"0",
"type":"SW"
}
]
Headers
Content-Type: application/jsonBody
[
{
"properties":{
"name":"s1-eth2",
"state":"1",
"type":"OF",
"bandwidth":"10000000000"},
"link":{
"port":"2",
"nodeId":"00:00:00:00:00:00:00:02"
}
}
}
]
Headers
Content-Type: application/jsonBody
[
{
"resultCode": 0,
"displayError": "No error",
"result": {
"Paths": [
"7a8b",
"dc6b"
]
}
]
Headers
Content-Type: application/jsonBody
{
directPathName: "81133498"
reversPathName: "16472338"
}
Headers
Content-Type: application/jsonBody
[
{
pathName: "81133498"
flow: {
nw_src: "10.0.0.1"
nw_dst: "10.0.0.3"
dp_src: "00:00:00:00:00:00:00:01"
dp_dst: "00:00:00:00:00:00:00:03"
dl_src: ""
dl_dst: ""
tp_src: ""
tp_dst: ""
bandwidth: ""
bidirectional: "1"
first_port: "1"
last_port: "1"
etherType: "0x800"
tosBits: ""
priority: "200"
protocol: ""
}
edgeList: [2]
0: {
headNode: "00:00:00:00:00:00:00:01"
tailNode: "00:00:00:00:00:00:00:02"
headPort: "2"
tailPort: "2"
}
1: {
headNode: "00:00:00:00:00:00:00:02"
tailNode: "00:00:00:00:00:00:00:03"
headPort: "3"
tailPort: "2"
}
}
]
Headers
Content-Type: application/jsonBody
[
{
ok
}
]
Headers
Content-Type: application/jsonBody
[
{
receiveFrameError: "0"
receiveCrcError: "0"
receiveDrops: "0"
receiveBytes: "1328"
receiveErrors: "0"
receiveOverRunError: "0"
transmitBytes: "797295"
transmitDrops: "0"
transmitErrors: "0"
transmitPackets: "5152"
collisionCount: "0"
}
]
Headers
Content-Type: application/jsonBody
[
{
packetCount: "0"
durationSeconds: "839"
byteCount: "0"
durationNanoseconds: "496000000"
}
]