Rest API

Live Documentation

https://raw.githubusercontent.com/openwisp/openwisp-network-topology/docs/docs/api-doc.png

A general live API documentation (following the OpenAPI specification) at /api/v1/docs/.

Browsable Web Interface

https://raw.githubusercontent.com/openwisp/openwisp-network-topology/docs/docs/api-ui.png

Additionally, opening any of the endpoints listed below directly in the browser will show the browsable API interface of Django-REST-Framework, which makes it even easier to find out the details of each endpoint.

List of Endpoints

Since the detailed explanation is contained in the Live Documentation and in the Browsable Web Interface of each point, here we'll provide just a list of the available endpoints, for further information please open the URL of the endpoint in your browser.

List Topologies

GET /api/v1/network-topology/topology/

Available filters:

  • strategy: Filter topologies based on their strategy (fetch or receive). E.g. ?strategy=<topology_strategy>.

  • parser: Filter topologies based on their parser. E.g. ?parser=<topology_parsers>.

  • organization: Filter topologies based on their organization. E.g. ?organization=<topology_organization_id>.

  • organization_slug: Filter topologies based on their organization slug. E.g. ?organization_slug=<topology_organization_slug>.

You can use multiple filters in one request, e.g.:

/api/v1/network-topology/topology/?organization=371791ec-e3fe-4c9a-8972-3e8b882416f6&strategy=fetch

Note

By default, /api/v1/network-topology/topology/ does not include unpublished topologies. If you want to include unpublished topologies in the response, use ?include_unpublished=true filter as following:

GET /api/v1/network-topology/topology/?include_unpublished=true

Create Topology

POST /api/v1/network-topology/topology/

Detail of a Topology

GET /api/v1/network-topology/topology/{id}/

Note

By default, /api/v1/network-topology/topology/{id}/ will return HTTP 404 Not Found for unpublished topologies. If you want to retrieve an unpublished topology, use ?include_unpublished=true filter as following:

GET /api/v1/network-topology/topology/{id}/?include_unpublished=true

Change Topology Detail

PUT /api/v1/network-topology/topology/{id}/

Patch Topology Detail

PATCH /api/v1/network-topology/topology/{id}/

Delete Topology

DELETE /api/v1/network-topology/topology/{id}/

View Topology History

This endpoint is used to go back in time to view previous topology snapshots. For it to work, snapshots need to be saved periodically as described in save_snapshot section above.

For example, we could use the endpoint to view the snapshot of a topology saved on 2020-08-08 as follows.

GET /api/v1/network-topology/topology/{id}/history/?date=2020-08-08

Send Topology Data

POST /api/v1/network-topology/topology/{id}/receive/

List Nodes

GET /api/v1/network-topology/node/

Available filters:

  • topology: Filter nodes belonging to a topology. E.g. ?topology=<topology_id>.

  • organization: Filter nodes belonging to an organization. E.g. ?organization=<organization_id>.

  • organization_slug: Filter nodes based on their organization slug. E.g. ?organization_slug=<organization_slug>.

You can use multiple filters in one request, e.g.:

/api/v1/network-topology/node/?organization=371791ec-e3fe-4c9a-8972-3e8b882416f6&topology=7fce01bd-29c0-48b1-8fce-0508f2d75d36

Create Node

POST /api/v1/network-topology/node/

Get Node Detail

GET /api/v1/network-topology/node/{id}/

Change Node Detail

PUT /api/v1/network-topology/node/{id}/

Patch Node Detail

PATCH /api/v1/network-topology/node/{id}/

Delete Node

DELETE /api/v1/network-topology/node/{id}/