API Introduction
CNM incluye un API (Application Programming Interface) que permite a los programadores integrar sus datos en aplicaciones de terceros de forma sencilla.
Se basa en servicios WEB de tipo REST (Representational State Transfer) sobre protocolo HTTPS.
Esto significa que utiliza los "verbos" GET, POST, PUT y DELETE definidos en dicho protocolo para implementar las diferentes acciones:
GET: Permite obtener información
POST: Permite crear un recurso
PUT: Permite actualizar un recurso
DELETE: Permite eliminar un recurso (1)
(1) En este momento sólo se soportan las peticiones de tipo GET, POST y PUT.
Las peticiones al API de CNM se pueden hacer desde un navegador, un terminal o un programa.
Los ejemplos que aparecen en esta documentación utilizan el programa curl que funciona sobre Unix o Windows, pero se podría haber utilizado cualquier otro programa que permita obtener datos mediante protocolo https como wget o código basado en cualquier lenguaje de programación.
Los datos devueltos por el API están codificados en JSON por su sencillez y por ser más compacto que otras alternativas comoXML.
El manejo de errores se debe hacer a partir de los códigos de retorno del protocolo HTTP.
A lo largo de la documentación se detallan los diferentes endpoints o métodos proporcionados.
ACCESO
El acceso es exclusivamente por SSL, desde una URL con el siguiente aspecto:
https://localhost/onm/api/1.0/endpoint.json
Los endpoints se corresponden con los métodos disponibles y se detallan en la documentación.
AUTENTICACIÓN
La mayor parte de los endpoints requieren autenticación.
Está basada en el uso de un token de acceso en cada petición que se incluye dentro de la cabecera HTTPAuthentication.
Dicho token se obtiene a través del endpoint:
GET auth/token.json
curl -ki "https://localhost/onm/api/1.0/auth/token.json?u=admin&p=cnm123"
Y se debe incuir de la siguiente forma:
Authorization: 854b5c0254572b995b3e96d8a05e31b9
ENDPOINTS DISPONIBLES
Actualmente están disponibles los siguientes endpoints:
- devices
- metrics
- views
- alerts
- tickets
- views
- profiles
- users
- backup
- embed/metric_graph
GET /auth/token.json
API endpoints need authentication with a token or session id.
This token must be suplied in the HTTP header HTTPAuthentication as shown in the following example::
Authorization: 854b5c0254572b995b3e96d8a05e31b9
This token is created with an expiration time of 180 seconds. After that period (or before) it should be necessary to renew it.
| GET /auth/token.json | Obtains the authentication token for the API endpoints. |
Parameters
| Name | Type | Mandatory | Default value | Description |
|---|---|---|---|---|
| u | Text | Yes | None | User name. |
| p | Text | Yes | None | User password. |
Response Code
| Code | Description |
|---|---|
| 200 | OK |
| 400 | Request error |
| 401 | Authentication error |
| 403 | Access permissions error |
| 500 | Internal error |
Return value
It is a JSON encoded value:
{"status":0,"sessionid":"04eea9a0eedeef04022ecbc2d38b7af3"}
| Name | Type | Default value | Description |
|---|---|---|---|
| status | Integer | None | Status |
| sessionid | Text | None | Token id |
Examples
curl -ki "https://10.2.254.222/onm/api/1.0/auth/token.json?u=admin&p=cnm123"
HTTP/1.1 200 OK
Date: Thu, 13 Feb 2014 12:52:26 GMT
Server: Apache/2.2.16 (Debian) PHP/5.3.3-7 with Suhosin-Patch proxy_html/3.0.1 mod_ssl/2.2.16 OpenSSL/0.9.8o mod_perl/2.0.4 Perl/v5.10.1
X-Powered-By: PHP/5.3.3-7
Expires: Thu, 19 Nov 1981 08:52:00 GMT
Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
Pragma: no-cache
:
Vary: Accept-Encoding
Content-Length: 59
Content-Type: text/html; charset=utf-8
{"status":0,"sessionid": "04eea9a0eedeef04022ecbc2d38b7af3"}