From d690bf006fcd977c940879920b3439303bb83171 Mon Sep 17 00:00:00 2001
From: Benjamin Bertrand <benjamin.bertrand@esss.se>
Date: Tue, 13 Feb 2018 15:54:05 +0100
Subject: [PATCH] Improve documentation
---
app/api/inventory.py | 11 +++++++
app/api/network.py | 11 +++++++
docs/api.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++
docs/conf.py | 7 +++--
docs/index.rst | 2 ++
5 files changed, 97 insertions(+), 3 deletions(-)
diff --git a/app/api/inventory.py b/app/api/inventory.py
index b863e68..8827024 100644
--- a/app/api/inventory.py
+++ b/app/api/inventory.py
@@ -65,6 +65,13 @@ def create_item():
.. :quickref: Inventory; Create new item
:jsonparam serial_number: serial number
+ :jsonparam ics_id: (optional) ICS id (temporary one generated if not present)
+ :jsonparam quantity: (optional) number of items [default: 1]
+ :jsonparam manufacturer: (optional) name of the manufacturer
+ :jsonparam model: (optional) name of the model
+ :jsonparam location: (optional) name of the location
+ :jsonparam status: (optional) name of the status
+ :jsonparam parent_id: (optional) parent id
"""
# People should assign an ICS id to a serial number when creating
# an item so ics_id should also be a mandatory field.
@@ -184,6 +191,7 @@ def create_manufacturer():
.. :quickref: Inventory; Create new manufacturer
:jsonparam name: manufacturer name
+ :jsonparam description: (optional) description
"""
return create_generic_model(models.Manufacturer)
@@ -207,6 +215,7 @@ def create_model():
.. :quickref: Inventory; Create new model
:jsonparam name: model name
+ :jsonparam description: (optional) description
"""
return create_generic_model(models.Model)
@@ -230,6 +239,7 @@ def create_locations():
.. :quickref: Inventory; Create new location
:jsonparam name: location name
+ :jsonparam description: (optional) description
"""
return create_generic_model(models.Location)
@@ -253,5 +263,6 @@ def create_status():
.. :quickref: Inventory; Create new status
:jsonparam name: status name
+ :jsonparam description: (optional) description
"""
return create_generic_model(models.Status)
diff --git a/app/api/network.py b/app/api/network.py
index 260331b..d20aa52 100644
--- a/app/api/network.py
+++ b/app/api/network.py
@@ -42,6 +42,7 @@ def create_scope():
:jsonparam last_vlan: network scope last vlan
:jsonparam supernet: network scope supernet
:jsonparam domain_id: primary key of the default domain
+ :jsonparam description: (optional) description
"""
return create_generic_model(models.NetworkScope, mandatory_fields=(
'name', 'first_vlan', 'last_vlan', 'supernet', 'domain_id'))
@@ -72,6 +73,10 @@ def create_network():
:jsonparam first_ip: first IP of the allowed range
:jsonparam last_ip: last IP of the allowed range
:jsonparam scope: network scope name
+ :jsonparam domain_id: (optional) primary key of the domain [default: scope domain]
+ :jsonparam admin_only: (optional) boolean to restrict the network to admin users [default: False]
+ :type admin_only: bool
+ :jsonparam description: (optional) description
"""
return create_generic_model(models.Network, mandatory_fields=(
'vlan_name', 'vlan_id', 'address', 'first_ip', 'last_ip', 'scope'))
@@ -99,6 +104,8 @@ def create_interface():
:jsonparam network: network name
:jsonparam ip: interface IP
:jsonparam name: interface name
+ :jsonparam mac_id: (optional) linked MAC address primary key
+ :jsonparam host_id: (optional) linked host primary key
"""
# The validate_interfaces method from the Network class is called when
# setting interface.network. This is why we don't pass network_id here
@@ -126,6 +133,9 @@ def create_host():
.. :quickref: Network; Create new host
:jsonparam name: hostname
+ :jsonparam type: Physical|Virtual
+ :jsonparam description: (optional) description
+ :jsonparam item_id: (optional) linked item primary key
"""
return create_generic_model(models.Host, mandatory_fields=('name',))
@@ -150,6 +160,7 @@ def create_macs():
.. :quickref: Network; Create new mac address
:jsonparam address: MAC address
+ :jsonparam item_id: (optional) linked item primary key
"""
return create_generic_model(models.Mac,
mandatory_fields=('address',))
diff --git a/docs/api.rst b/docs/api.rst
index e9b8b93..7853909 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -73,6 +73,68 @@ Here is a header example for the following query::
The `x-total-count` header is also sent back and set to the total number of elements returned by the query.
+Filtering
+---------
+
+When sending a `GET` request, you can pass parameters in the query string to filter the results.
+
+If you want to retrieve all items with the status "Loaned".
+
+1. Get the id of the "Loaned" status::
+
+ curl -H "Authorization: Bearer $TOKEN" $URL/api/v1/inventory/statuses?name=Loaned
+
+ Example response::
+
+ [
+ {
+ "description": null,
+ "id": 4,
+ "name": "Loaned",
+ "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAKUAAAClAQAAAAAVUAB3AAABYElEQVR4nO2XTW7bMBBG30gFqB19A/oisZp7KZUKB+ixKtUXkW9A7ShA1teF226a7DJBC4Qr4lvMw/yTJv4+a/WCCB/qv6MiZcAyqUAH0Kt40nppkmbtcUtSdqRVwM0aFjuuFWDV29l9XY1bCruD3VfUbxOX6/AOtFqFZWBt04B2T9qfmuxSmPI71OTvU9rc/7o5RnJ5OjIdngG48mMZXCOpgbBTS8pdovX0DSnXsyad52LSXMyzu++zpJyopSl3hDH65i3asbloYP0MrI/XwTdvG2GHVIhbCq41ee83jdSzdjrkGkkkbamcolTaDGH07O4Klk80l6tZA7B+eTO7L6tRs3Z6hZFeXLIvbTGzimfWituRh4MvjV4a45OF74d6xrIz7WYN1Foe81dDB0caUu4Ik7ZUiGdhzjsAgOU8BeWb8WCDr2/3N5dKqy1p8p7KgOUOTnFLxXV328ev479UfwKVEPNjwev1VAAAAABJRU5ErkJggg=="
+ }
+ ]
+
+2. Get the items with status_id 4::
+
+ curl -H "Authorization: Bearer $TOKEN" $URL/api/v1/inventory/items?status_id=4
+
+ Example response::
+
+ [
+ {
+ "children": [],
+ "comments": [
+ "Will be sent to Freia with fan-out.\n",
+ "delivered to BI temporarily ",
+ "Imported from JIRA TAG-15"
+ ],
+ "created_at": "2014-04-22 08:39",
+ "history": [
+ {
+ "location": "ESS",
+ "parent": null,
+ "quantity": 1,
+ "status": "Loaned",
+ "updated_at": "2018-02-05 14:28"
+ }
+ ],
+ "ics_id": "ZZA014",
+ "id": 15,
+ "location": "ESS",
+ "macs": [],
+ "manufacturer": "Schroff",
+ "model": "Compact PCI Crate 2U 4 slot",
+ "parent": null,
+ "quantity": 1,
+ "serial_number": "BGRR 2HE 24579 081 1291200686 BB",
+ "status": "Loaned",
+ "updated_at": "2018-02-05 14:28",
+ "user": "Inigo Alonso"
+ },
+ ...
+ ]
+
Resources
---------
@@ -104,3 +166,10 @@ Network
.. autoflask:: wsgi:app
:modules: app.api.network
:order: path
+
+
+Client
+------
+
+A Python client library is available to access CSEntry API:
+`csentry-api <http://ics-infrastructure.pages.esss.lu.se/csentry-api/index.html>`_
diff --git a/docs/conf.py b/docs/conf.py
index 3f9bb76..07beee3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -183,7 +183,8 @@ texinfo_documents = [
]
-
-
# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/3/': None}
+intersphinx_mapping = {
+ 'python': ('https://docs.python.org/3/', None),
+ 'csentry-api': ('http://ics-infrastructure.pages.esss.lu.se/csentry-api/', None),
+}
diff --git a/docs/index.rst b/docs/index.rst
index f305680..afc4657 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,6 +6,8 @@
Welcome to CSEntry's documentation!
===================================
+Release v\ |version|.
+
Control System Entry is a web application that facilitates the tracking of physical items
and network devices.
--
GitLab