Skip to content

Commit f435260

Browse files
cmeissnercmeissner
authored
Update README.md
1 parent 43184f8 commit f435260

File tree

1 file changed

+162
-6
lines changed

1 file changed

+162
-6
lines changed

‎README.md‎

Lines changed: 162 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,36 @@
1-
# phpypam: Python API client library for phpIPAM installation
2-
31
[![PyPI version](https://badge.fury.io/py/phpypam.svg)](https://badge.fury.io/py/phpypam)
42
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/ed3511c33a254bfe942777c9ef3251e3)](https://www.codacy.com/gh/codeaffen/phpypam/dashboard?utm_source=github.com&utm_medium=referral&utm_content=codeaffen/phpypam&utm_campaign=Badge_Grade)
53
[![Documentation Status](https://readthedocs.org/projects/phpypam/badge/?version=latest)](https://phpypam.readthedocs.io/en/latest/?badge=latest)
64

7-
phpypam is intended to be a complete library for speaking with phpIPAM API.
5+
As we started to develop phpipam-ansible-modules we used an existing python library for phpIPAM API. As we needed a good error handling and we don't expect a quick fix of existing project we started to develop our own library.
6+
7+
## installation
8+
9+
This library is hosted on [pypi.org](https://pypi.org/project/phpypam/), so you can simply use `pip` to install it.
10+
11+
~~~bash
12+
pip install phpypam
13+
~~~
814

9-
Using `phpypam` is as easy as using the UI.
15+
Alternatively you can install it from source. You need to do the following:
1016

11-
```python
17+
~~~bash
18+
$ git clone https://github.com/codeaffen/phpypam.git
19+
Cloning into 'phpypam'...
20+
remote: Enumerating objects: 1, done.
21+
remote: Counting objects: 100% (1/1), done.
22+
remote: Total 366 (delta 0), reused 0 (delta 0), pack-reused 365
23+
Receiving objects: 100% (366/366), 88.57 KiB | 521.00 KiB/s, done.
24+
Resolving deltas: 100% (187/187), done.
25+
$ cd phpypam/
26+
$ python setup.py install
27+
~~~
28+
29+
## quick start
30+
31+
To start using `phpypam` you simply have to write some lines of code.
32+
33+
~~~python
1234
import phpypam
1335

1436
pi = phpypam.api(
@@ -19,4 +41,138 @@ pi = phpypam.api(
1941
ssl_verify=True
2042
)
2143
pi.get_entity(controller='sections')
22-
```
44+
~~~
45+
46+
## making api connection
47+
48+
To connect to phpIPAM API you need some parameter to authenticate against the phpIPAM instance.
49+
50+
Parameter | Description | Default |
51+
:-------- | :---------- | :------ |
52+
url | The URL to a phpIPAM instance. It includes the protocol (http or https). | |
53+
app_id | The app_id which is used for the API operations. |
54+
username | The `username` which is used to connect to API. | None |
55+
password | The `password` to authenticate `username` against API. | None |
56+
ssl_verify | Should certificate of endpoint verified or not. Useful if you use a self signed certificate. | True |
57+
58+
*Example* connect to api and request current token:
59+
60+
~~~python
61+
connection_params = dict(
62+
url='https://ipam.example.com',
63+
app_id='ansible',
64+
username='apiuser',
65+
password='apiP455wd',
66+
ssl_verify=True
67+
)
68+
69+
pi = phpypam.api(**connection_params)
70+
71+
token = pi.get_token()
72+
~~~
73+
74+
First of all you create a dictionary with the connection data. This dictionary will unpacked for creating a `phpypam.api` object.
75+
76+
If all went well you can use the `get_token` to get the currently valid token from API.
77+
78+
## get available controllers
79+
80+
To work with the phpIPAM api it is useful if you know all available controllers. To achieve this you can either read the api documentation or you can use the `controllers` method.
81+
82+
~~~python
83+
controllers = pi.controllers()
84+
~~~
85+
86+
The method returns a set with all supported controllers.
87+
88+
## get an entity
89+
90+
To get an entity the `get_entity` method has to be used.
91+
92+
~~~python
93+
get_entity(controller, controller_path=None, params=None)
94+
~~~
95+
96+
*Example* get a `section` by name:
97+
98+
~~~python
99+
entity = pi.get_entity(controller='sections', controller_path='foobar')
100+
~~~
101+
102+
This call returns a dictionary for the entity with the name `foobar`.
103+
104+
## create an entity
105+
106+
To create an entity the `create_entity` method has to be used.
107+
108+
~~~python
109+
create_entity(controller, controller_path=None, data=None, params=None)
110+
~~~
111+
112+
*Example* create a `section` if it does not exists:
113+
114+
~~~python
115+
my_section = dict(
116+
name='foobar',
117+
description='new section',
118+
permissions='{"3":"1","2":"2"}'
119+
)
120+
121+
try:
122+
entity = pi.get_entity(controller='sections', controller_path=my_section['name'])
123+
except PHPyPAMEntityNotFoundException:
124+
print('create entity')
125+
entity = pi.create_entity(controller='sections', data=my_section)
126+
127+
~~~
128+
129+
In this example first we check if the section we work on already exists. If the PHPyPAMEntityNotFoundException is raised we create the entity.
130+
131+
## update an entity
132+
133+
To update an entity you have to use the `update_entity` method.
134+
135+
~~~python
136+
update_entity(controller, controller_path=None, data=None, params=None)
137+
~~~
138+
139+
*Example* update a `section` if it exists:
140+
141+
~~~python
142+
my_section['description'] = 'new description'
143+
144+
entity = pi.get_entity(controller='sections', controller_path=my_section['name'])
145+
pi.update_entity(controller='sections', controller_path=entity['id'], data=my_section)
146+
~~~
147+
148+
To change data you have to modify the value of the desired key to the value you want. You can see the data is changed in the dict from the former example.
149+
Then you get the entity to obtain its id to work on.
150+
151+
**Note:** All modifying operations need the id of an entity not the name.
152+
153+
In the last step you call `update_entity` and put the entity id in parameter `controller_path` with the `data` parameter you provide the fully entity description dictionary.
154+
155+
## delete an entity
156+
157+
To delete an entity you have to use the `delete_entity` method.
158+
159+
~~~python
160+
delete_entity(controller, controller_path, params=None)
161+
~~~
162+
163+
*Example* delete a existing section:
164+
165+
~~~python
166+
entity = pi.get_entity(controller='sections', controller_path=my_section['name'])
167+
pi.delete_entity(controller='sections', controller_path=entity['id'])
168+
~~~
169+
170+
In this example you request the entity you had created/updated in the above examples.
171+
After that you call `delete_entity` with the entity id from the request before.
172+
173+
## possible exceptions
174+
175+
* ***PHPyPAMInvalidCredentials*** - will be raised if something goes wrong with the authentication
176+
* ***PHPyPAMEntityNotFoundException*** - will be raised if an entity does not exists
177+
* ***PHPyPAMInvalidSyntax*** - will be raised for requests which will be answered with status code 400 from API
178+
* ***PHPyPAMException*** - for any errors which we catch but no specific exception exists this exception wil be raised

0 commit comments

Comments
 (0)