Have questions? Stuck? Please check our FAQ for some common questions and answers.

Auto-generated Swagger Documentation

ONOS uses Swagger to auto-generate REST API documentation. This can be viewed from any running ONOS instance at the following URL: http://<ONOS IP>:8181/onos/v1/docs/.

This also offers a nice way to directly run queries or copy&paste curl commands for testing. Endpoints contributed by non-core applications can be reached through the top menu.

Summary of Core APIs

The following specifications are manually-written documentation, so it will inevitably fall out-of-sync with the code. It is recommended to use the above instructions to access the automatically-generated Swagger documentation for the most up-to-date information.

Please note that the all endpoints need to be prefixed with: http://<controller IP>:8181/onos/v1/

Example: http://127.0.0.1:8181/onos/v1/devices if ONOS is running on your local machine.

The entries in bold are currently implemented.

Device

GET /devicesLists all infrastructure devices.
GET /devices/{deviceId}Lists details of a specific infrastructure device.
GET /devices/{deviceId}/portsLists ports of a specific infrastructure device.
POST /devicesCreates a new infrastructure device into inventory (future).
PUT /devices/{deviceId}Updates a device - attributes, availability, mastership.
DELETE /devices/{deviceId}Deletes an infrastructure device from inventory.
GET /linksLists all infrastructure links.
GET /links?{device=deviceId}{port=portNumber}{direction=[ALL,INGRESS,EGRESS]}Lists details of a link.
POST /linksCreates a new infrastructure link into inventory (future).
PUT /links/{linkId}Updates a link - attributes, e.g. type.
DELETE /link/{linkId}Deletes an infrastructure link from inventory.

Host

GET /hostsLists all end-stations hosts.
GET /hosts/{hostId}Lists details of a specific end-station host specified by the host ID.
GET /hosts/{mac}/{vlan}Lists details of a specific end-station host specified by the host MAC address and VLan Id.
POST /hostsCreates a new end-station host into inventory (future).
PUT /hosts/{hostId}Updates an end-station host - attributes, e.g. IP, location.
DELETE /hosts/{hostId}Deletes an end-station host from inventory.

Topology

GET /topologyGets overview of the current topology.
GET /topology/clustersGets list of topology cluster overviews.
GET /topology/clusters/{clusterId}Gets overview of a specific topology cluster.
GET /topology/clusters/{clusterId}/devicesGets infrastructure devices that belong to the specified topology cluster.
GET /topology/clusters/{clusterId}/linksGets infrastructure links that belong to the specified topology cluster.
GET /topology/broadcast/{connectPoint}Gets indication whether the given point permits broadcast.
GET /topology/infrastructure/{connectPoint}Gets indication whether the given point belongs to network infrastructure.

Path

GET /paths/{elementId}/{elementId}Gets set of pre-computed shortest paths between the specified source and destination network elements.

Flow  

POST /flows/{deviceId}Creates a single flow rule applied to the specified infrastructure device.
GET /flows/{deviceId}Gets list of flow rules applied to the specified infrastructure device.
GET /flows/{deviceId}/{flowId}Gets details of a specified flow rule.
GET /flowsGets details of all flow rules in the system.
POST /flows/

Adds a batch of flow rules.

DELETE /flows/{deviceId}/{flowId} Deletes a flow rule from the specified device.
GET /statistics/flows/link/{linkId}Gets aggregate statistics for all flows traversing the given link.

Flow Objectives

POST /flowobjectives/{deviceId}/filterCreates and installs a new filtering objective for the specified device.
POST /flowobjectives/{deviceId}/forwardCreates and installs a new forwarding objective for the specified device.
POST /flowobjectives/{deviceId}/nextCreates and installs a new next objective for the specified device.
GET /flowobjectives/nextGets the globally unique nextId.
POST /flowobjectives/policyInstalls the filtering rules onto the specified device.

Group

POST /groups/{deviceId}Creates a single group entry applied to the specified infrastructure device.
GET /groups/{deviceId}Gets list of group entries applied to the specified infrastructure device.
GET /groups/{deviceId}/{groupKey}Gets details of a specified group entry.
GET /groupsGets details of all group entries in the system.
DELETE /groups/{deviceId}/{groupKey} Deletes a group entry from the specified device.

Meter

POST /meters/{deviceId}Creates a single meter entry applied to the specified infrastructure device.
GET /meters/{deviceId}Gets list of meter entries applied to the specified infrastructure device.
GET /meters/{deviceId}/{meterId}Gets details of a specified meter entry.
GET /metersGets details of all meter entries in the system.
DELETE /meters/{deviceId}/{meterId} Deletes a meter entry from the specified device.

Intent

GET /intents/{app-id}/{intent-id}Gets the details for the given Intent object.
GET /intentsGets a collection containing all the Intent objects currently in the system.
POST /intentsCreates a new Intent object.
POST /intentsCreates a batch of Intent objects (pending -may not be included in finalized API).
DELETE /intents/{app-id}/{intent-id}Removes an intent from the system.

Application

GET /applicationsGets a list of all installed applications.
GET /applications/{app-name}Gets information about the named application.
POST /applications/Installs application using the posted app.xml or application package file (ZIP).
DELETE /applications/{app-name}Uninstalls the named application.
POST /applications/{app-name}/activeActivates the named application.
DELETE /applications/{app-name}/activeDeactivates the named application.
GET /applications/ids/entryGets applicationId entry by either id or name
GET /applications/ids/Gets a list of all registered applicationIds

Component Configuration

Each OSGI component within ONOS can have its own set of configuration values.  The REST APIs present these as a map when generating JSON:

{
    "org.onosproject.provider.host.impl.HostLocationProvider":
    {
        "ipv6NeighborDiscovery":"false",
        "hostRemovalEnabled":"true"
    }
}
GET /configurationGets a list of all active components and their configuration values
GET /configuration/{component}Gets the configuration values for a single component
POST /configuration/{component}Adds a set of configuration values to a component
DELETE /configuration/{component}Removes the configuration values for a component and sets them back to their default values



Previous : Appendix A : List of ONOS Test Scripts (onos-* scripts)
Next : Appendix C : Source Tree Organization




  • No labels

2 Comments

  1. Is there a way to test this in 1.0 ? I installed the onos-rest feature but it didnt seem to change anything ?

  2. The base URL for the REST APIs is: http://<controller IP>:8181/onos/v1/

    I can update the wiki page to reflect this.