Introduction.
NetworkMaps provides the option of modifying your network diagrams using external scripts. This is done by establishing a set of websocket connections to the server and sending messages on these sessions (using JSON format). This is the same mechanism used by the GUI.
There are two channels where you can connect:
- /user: Used to manage your user account and where you create, delete or manage your diagrams.
- /diagram/<diagram uuid>: Used to edit your diagrams. Every diagram has a unique uuid. Through the /user channel we can list all the diagrams with their uuids.
Normal Flow.
When using NetworkMaps API, you will usually follow these steps:
- Set up an authenticated session (if you already have an authenticated session, you can skip this step). Networkmaps uses a cookie to maintain sessions: (NetSessionSec for https or NetSessionNoSec for http).
- When a new connection is established, networkmaps will create this cookie if it is not provided or the provided session is invalid. A session can be authenticated or not.
- On websocket connection, the networkmaps user channel will send an initial message letting you know if your session is authenticated and by which user.
- If the session is not authenticated, you will have to send an authentication message with username and password.
- Get uuid of the diagram to be edited/updated (or create a new diagram).
- Set up a connection to the diagram enpoint using the already authenticated session.
- Update the diagram.
The User Channel.
When a client connects to the use channel, he will receive an initial message telling him if the session used is initialized. This message has the following format:
{"m": "I", "d": <session_data> "session_id": <session_id>}
- m: Type of message. Initialization messages will have this key set to "I".
- data: Object containing session data. This Oject will have the user data if the session is authenticated:
- user: username that is authenticated.
- name: name of the user.
- lastname: last name of the user.
- session_id: Session ID used in this connection. This will match the NetSessionSec/NetSessionNoSec cookie if the session id was valid. If not, NetworkMaps will create a new session.
In general all messages sent or received on this channel will follow this format: {"m": "I", "d": <session_data>}. Where m defines the message type we are sending/receiving and d will be an object with the parameters of this message.
These are the messages types we can use:
- L: Log in.
- O: Log out.
- D: Change Data.
- X: Change password.
- R: Reset Password.
- C: Create User.
- DN: Create Diagram.
- DL: List Diagrams.
- DD: Delete Diagram.
- DR: Rename Diagram.
- DP: Get permissions of a Network Diagram
- PD: Delete permissions.
- DS: Share Diagram.
The Diagram Channel.
TODO
Follow @masshandra
NetworkMaps