HTTP services ************* Rotonda runs an HTTP server providing a (very basic) Web UI, metrics in Prometheus format, and various JSON endpoints. All these are served on one single port, configured in `rotonda.conf`. Note that even though the endpoints are under ``/api/v1``, this does not mean everything on this page is considered stable at this point. Web UI ****** The web UI lives at the root of the configured web server. It provides a simple overview of the basics. These pages should not be scraped, use the JSON endpoints to fetch information properly. Prometheus metrics ****************** On ``/metrics`` a Prometheus style file is served. This currently contains a mix of metrics from Rotonda itself, and possibly user-defined metrics from Roto filters. .. warning:: The metrics defined by Rotonda itself are soon to be overhauled, and currently in sub-optimal shape after various refactors of the codebase. Some counters will always be 0, some will be incorrect. Use these to get a general idea of activity of the system, but not for accurate numbers whatsoever. JSON endpoints ************** .. important:: While under ``/api/v1``, these endpoints are considered under development and might change without a version bump in the URL. Rotonda offers endpoints to query information on `ingresses`, i.e. sources of routing information such as BMP streams or BGP sessions, and on routes stored in the RIBs. Both these endpoints allow filtering in the query part of the request. .. confval:: GET /api/v1/ingresses[?filter[A]=x[&filter[B]=y]..] Returns all the `ingresses` for this Rotonda instance. The filter options below can be combined, and will be evaluated in boolean **AND** fashion. - ``?filter[type]=`` where **** can be one of ``bmp``, ``bgpViaBmp``, ``bgp``, ``mrt``. - ``?filter[ribType]=`` where **** can be one of ``inPre``, ``inPost``, ``loc``, ``outPre``, ``outPost``. - ``?filter[peerAddress]=`` where **** is an IPv6 or IPv4 address. - ``?filter[peerAsn]=`` where **** is an Autonomous System Number, possibly prefixed with "AS". .. confval:: GET /api/v1/ribs/ipv4unicast/routes//[?filter[A]=x[&filter[B]=y]..] Returns all the active routes for this IPv4 Unicast prefix. The filter options below can be combined, and will be evaluated in boolean **AND** fashion. Filters ======= - ``?filter[originAsn]=`` where **** is an Autonomous System Number, possibly prefixed with "AS". - ``?filter[otc]=`` filters on the Only-To-Customer path attribute, where **** is an Autonomous System Number, possibly prefixed with "AS". - ``?filter[community]=`` filters on a standard Community (RFC1997), where **** is either in canonical ``AS65412:666`` form, or the name of a well-known communitiy e.g. ``NO_PEER``. - ``?filter[largeCommunity]=`` filters on a Large Community (RFC8092), where **** is in canonical ``AS65412:1234:9999`` form. - ``?filter[ribType]=`` where **** can be one of ``inPre``, ``inPost``, ``loc``, ``outPre``, ``outPost``. - ``?filter[rovStatus]=`` where **** can be one of ``notChecked``, ``notFound``, ``valid``, ``invalid``. - ``?filter[peerAsn]=`` where **** is an Autonomous System Number, possibly prefixed with "AS". - ``?filter[peerAddress]=`` where **** is an IPv6 or IPv4 address. Functions ========= - ``?function[roto]=`` where **** is the name of a user-defined Roto function taking :roto:ref:`PathAttributes ` as a parameter, and indicating via ``accept`` or ``reject`` whether a route should be included in the response. For example, the filter returns routes that contain both an ``OTC`` and ``AS_PATH`` path attribute where the ASN for the OTC is not part of the ``AS_PATH``. .. code-block:: rust fn my_filter_function(attr: PathAttributes) { match attr.otc() { Some(otc) -> { match attr.aspath() { Some(aspath) -> { if not aspath.contains(otc) { accept } else { reject } }, None -> reject, } } None -> { reject } } } Fields ====== Fields can be used to override the default output fields of parts of the response. This can help to greatly reduce the size of responses. Note that this is different from *filtering*. - ``?fields[pathAttributes]=`` where **** is a comma separated list of integers, representing one or multiple types of path attibutes. Only path attributes of these types will be included in the response. For example, to only return the Standard and Large communities: .. code-block:: /api/v1/ribs/ipv4unicast/routes?fields[pathAttributes]=8,32 Includes ======== Includes are used to incorporate data additional to the exact prefix searched for. The ``filter``s and ``field``s are applied on these as well. .. danger:: Including routes for more-specific prefixes via ``include=moreSpecifics`` can result in very large responses. - ``?include=`` where **** is a comma separated list of one or multiple of: ``moreSpecifics``, ``lessSpecifics``. .. FIXME what about IngressId, why is this not in filter[] ? .. confval:: GET /api/v1/ribs/ipv6unicast/routes// Returns all the active routes for this IPv6 Unicast prefix. Takes the same ``filter``, ``fields``, ``function`` and ``include`` as the ipv4 unicast endpoint described above. .. danger:: Depending on the volume of routes in the RIB, querying the endpoints below can be expensive, and/or result in huge responses. .. confval:: GET /api/v1/ribs/ipv4unicast/routes Returns all the active routes for the entire IPv4 Unicast address family. This mimics a request to ``/api/v1/ribs/ipv4unicast/0.0.0.0/0?include=moreSpecifics`` and as such, all results will be part of the `included` object in the response: .. code-block:: { .. "included": { "moreSpecifics": [ .. ] } } Takes the same ``filter``, ``fields``, ``function`` and ``include`` as the ipv4unicast endpoint described above. .. confval:: GET /api/v1/ribs/ipv6unicast/routes Returns all the active routes for the entire IPv6 Unicast address family, similar to the IPv4 Unicast endpoint described above.