From aafd5a80db7b5ee27d1c432a4db93da48fbecb8a Mon Sep 17 00:00:00 2001
From: Kristian Lyngstol <kly@kly.no>
Date: Fri, 4 Mar 2016 17:47:56 +0000
Subject: nms: Rename API end points and separate public/private

---
 web/nms.gathering.org/api/API.rst | 90 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 web/nms.gathering.org/api/API.rst

(limited to 'web/nms.gathering.org/api/API.rst')

diff --git a/web/nms.gathering.org/api/API.rst b/web/nms.gathering.org/api/API.rst
new file mode 100644
index 0000000..b56db64
--- /dev/null
+++ b/web/nms.gathering.org/api/API.rst
@@ -0,0 +1,90 @@
+API-dok
+=======
+
+Work in progress.
+
+General: All end-points that output time-based data accept the "now=<time>"
+argument, where, <time> is YYYY-MM-DDThh:mm:ss. E.g:
+
+GET /switch-state.pl?now=2015-04-02T15:00:00
+
+There is no guarantee that the data is exact time-wise, thus each endpoint
+should also output relevant time stamps.
+
+Currently error handling sucks.
+
+This document is in no way complete, but it's a start. It will be updated
+as time permits and API's stabilize.
+
+comment-add.pl
+--------------
+
+Methods: POST
+
+ -- Add a comment
+
+comment-change.pl
+-----------------
+
+Methods: POST
+
+Note that comments are never really deleted, but the state can be set to
+deleted, making sure they are never shown.
+
+comment.pl -- View comments
+---------------------------
+
+Methods: GET
+Update frequency: on user input
+
+ping.pl -- Being phased out
+---------------------------
+
+Methods: GET
+Update frequency: every second or so.
+
+Used to report switch latency and linknet latency.
+
+The switch latency is being integrated into switch-state.pl and linknet
+latency will similarly be moved.
+
+port-state.pl -- Get per-port statistics
+----------------------------------------
+
+Methods: GET
+Update frequency: Every few seconds, based on SNMP data.
+
+Private.
+
+Returns detailed per-port statistics. Being somewhat reorganized but will
+remain highly relevant.
+
+switches_add.pl -- Add a switch
+-------------------------------
+
+Methods: POST
+
+Add switches, supports same format as tools/add_switches.txt.pl
+
+Accepts an array of switches.
+
+switches.pl
+-----------
+
+Methods: GET
+Update frequency: Infrequent (on topology/config changes)
+
+List all switches and map positions. Output is filtered for public users.
+
+Used to draw switches on a map and provide static information.
+
+switch-state.pl -- List state for switches
+------------------------------------------
+
+Methods: GET
+Update frequency: Every second
+
+Provides state for each switch, including total port speed, uplink port
+speed, latency and temperature.
+
+100% public.
-- 
cgit v1.2.3