API - noms-ops/cmdb-api GitHub Wiki

Content

Intro

There are three categories of URL endpoints that the API provides:

  • device (or system) entity
  • generic entity
  • special APIs

The CMDB API attempts to be restful as an HTTP REST API. The API currently only has full suport for JSON input and output. As the API is driven by the pp_lexicon.xml schema definition document and the cmdb_api.conf config file, the number of resources or URL endpoints is defined as a part of the configuration of the installation. Several basic entity types are defined in the default configuration. For these, all of them, except for the device (system) entity behave the same way, with some variation for the device endpoint. The API supports GET/PUT/POST/DELETE for almost all objects, but PUT behaves more like the proposed 'PATCH' verb. For each of these APIs, operations are performed rest-fully against the URL endpoint using the GET/PUT/POST/DELETE verbs. For device and generic the usage of the verbs is the same:

  • GET: returns resource or array of resources. The resource is returned directly when accessed using the key and the URL endpoint. When URL search parameters are used, an array of resources is returned, even if one or zero resources match the search criteria. An array of all resources is also returned when access the resource endpoint without a key.
  • PUT: for idempotent edit operations on a resource. Must be accessed via the full URL resource endpoint with key. ( /cmdb_api/v1/system/webserver01.exmple.com )
  • POST: for non-idempotent create operations of the endpoint resource type

Authentication is handled by the underlying apache config. If auth has been enabled (should have been) then all URL endpoints (except for trafficcontrol) require basic authentication.

Schema

The schema provided by the API can be viewed by hitting the following URL: /cmdb_api/v1/?lexicon=1

The output from this URL will include the full schema, including all entities and their attributes. To view a list of entities, access /cmdb_api/v1/?help=1 Further, you can then for each entity, access the entity schema by appending ?help=1 to the resource location: /cmdb_api/v1/system?help=1

Device (system) & generic entity API

Create

Description: To create a new device or entity of any type perform a POST to the URL endpoint for that entity, including the data (JSON encoded) in the body of the POST. Any and all attributes of the resource can be included in the POST body. (however, if date_created or date_modified are included, they will be ignored)

Request: POST /cmdb_api/v1/<ENTITY>

Example:

curl -v -uusername:password -XPOST http://localhost/cmdb_api/v1/system/ \ 
-d'{"fqdn":"test3.example.com","ipaddress":"10.10.10.12","macaddress":"00:16:3e:00:4e:98"}'

The HTTP 201 response will contain a header entry, Location, with the URL to the newly created resource:

> POST /cmdb_api/v1/system/ HTTP/1.1
> Authorization: Basic XXX=
> User-Agent: curl/7.30.0
> Host: localhost
> Accept: */*
> Content-Length: 87
> Content-Type: application/x-www-form-urlencoded
> 
* upload completely sent off: 87 out of 87 bytes
< HTTP/1.1 201 Created
< Date: Tue, 03 Dec 2013 16:36:39 GMT
< Location: /cmdb_api/v1/system/test3.example.com
< Content-Length: 0
< Content-Type: text/plain

Update

Description: Update an entity by PUT'ing to the URL resource of the entity, including the data (JSON encoded) in the body of the PUT. NOTE the API treats PUT requests like PATCH. Updating the included attributes of the resource, not replacing the entire resource with the body sent.

Request: PUT /cmdb_api/v1/<ENTITY>/<KEY>

Example:

curl -v -uusername:password -XPUT http://localhost/cmdb_api/v1/system/test3.example.com \
-d '{"ipaddress":"110.110.110.12","note":"system recently moved to new subnet"}'

The HTTP 200 response will contain the resource as would be returned with a GET. (the output below has been truncated)

> PUT /cmdb_api/v1/system/test3.example.com HTTP/1.1
> Authorization: Basic XXX=
> User-Agent: curl/7.30.0
> Host: localhost
> Accept: */*
> Content-Length: 75
> Content-Type: application/x-www-form-urlencoded
> 
* upload completely sent off: 75 out of 75 bytes
< HTTP/1.1 200 OK
< Date: Tue, 03 Dec 2013 17:06:05 GMT
< Transfer-Encoding: chunked
< Content-Type: application/json
< 
{
   "serial_number" : null,
   "fqdn" : "test3.example.com",
   "macaddress" : "00:16:3e:00:4e:98",
   "inventory_component_type" : "system",
   "virtual" : null,
   "data_center_code" : null,
   "status" : "idle",
   "date_created" : "0000-00-00 00:00:00",
   "date_modified" : "2013-12-03 09:06:05",
   "ipaddress" : "110.110.110.12",
}

Reading or finding a entity

Description: The REST endpoint for accessing a resource or searching for resources is the same entity endpoint used for update operations. To search for a resource, you add URL query parameters to the URL. Any attribute can be searched against, using wildcards or one of the following operators:

  • = equals, wildcards (*) are multicharacter matching
  • != not equals

  • greater than, works with numbers and dates (using mysql date string formats)

  • < less then
  • ~ regex match (uses mysql RLIKE)
  • !~ not regex match (uses mysql NOT RLIKE)

All search parameters are AND ed together. This mostly means that OR searching is not possible. But you can use the regex search with | (pipe) character to OR search against a single attribute. Additionally, you can only search against an attribute once. So ?notes=*moved*&notes=*datacenter* will not work.

Request: GET /cmdb_api/v1/<ENTITY>/<KEY> OR GET /cmdb_api/v1/<ENTITY>/?<SEARCH PARAMS>

Example: (objects returned have been truncated) curl -uusername:password -XGET http://localhost/cmdb_api/v1/system/test3.example.com

Returns the resource:

{
   "serial_number" : null,
   "fqdn" : "test3.example.com",
   "macaddress" : "00:16:3e:00:4e:98",
   "inventory_component_type" : "system",
   "virtual" : null,
   "data_center_code" : null,
   "status" : "idle",
   "date_created" : "0000-00-00 00:00:00",
   "date_modified" : "2013-12-03 09:06:05",
   "ipaddress" : "110.110.110.12",
}

Searching curl -uusername:password -XGET http://localhost/cmdb_api/v1/system/?fqdn=test3.example.com

[
 {
   "serial_number" : null,
   "fqdn" : "test3.example.com",
   "macaddress" : "00:16:3e:00:4e:98",
   "inventory_component_type" : "system",
   "virtual" : null,
   "data_center_code" : null,
   "status" : "idle",
   "date_created" : "0000-00-00 00:00:00",
   "date_modified" : "2013-12-03 09:06:05",
   "ipaddress" : "110.110.110.12",
 }
]

a search that will return no resources curl -uusername:password -XGET http://localhost/cmdb_api/v1/system/?fqdn=test3333.example.com


[]

a regex search curl -uusername:password -XGET http://localhost/cmdb_api/v1/system/?fqdn~test[2|3]

[
   {
      "serial_number" : null,
      "fqdn" : "test2.example.com",
      "macaddress" : "00:16:3e:00:4e:99",
      "inventory_component_type" : "system",
      "virtual" : null,
      "status" : "idle",
      "date_modified" : "2013-12-03 08:36:03",
      "ipaddress" : "10.10.10.11"
   },
   {
      "serial_number" : null,
      "fqdn" : "test3.example.com",
      "macaddress" : "00:16:3e:00:4e:98",
      "inventory_component_type" : "system",
      "virtual" : null,
      "status" : "idle",
      "date_created" : "0000-00-00 00:00:00",
      "date_modified" : "2013-12-03 09:06:05",
      "ipaddress" : "110.110.110.12"
   }
]

Special APIs

currentUser

Description: The currentUser api simply returns information about the currently authenticated user. This API is used by the cmdb-ui. Request: GET /cmdb_api/v1/currentUser/

Example:

{
   "sshkey" : "",
   "groups" : "Admin",
   "systemuser" : "0",
   "writeaccess" : "1",
   "username" : "admin"
}

nccsystemname

Description: nccsystemname is an API primarily to server for provisioning of device/system resources. Using the prism_domain defined in the cmdb_api.conf, the API will find or create a new system/device entry and returns the name. The naming scheme is simply an 8 character name based on auto-incrementing and the domain specified.

Request: GET /nccsystemname/<SERIAL NUMBER>

Example: curl -v -uuseranme:password 'http://localhost/cmdb_api/v1/pcmsystemname/12345'

a new record has been created and the fqdn of the new record is returned. additional calls to the URL will result in the same output, with no new records being created.

{
   "fqdn" : "m0000150.example.com"
}

column_lkup

Description: This API serves as a utility to return a unique set of values for an attribute of a given resource.

Request: GET /cmdb_api/v1/column_lkup/<ENTITY>/<ATTRIBUTE>

Example: http://localhost/cmdb_api/v1/column_lkup/system/manufacturer


[
   "Dell",
   "HP",
   "iXsystems",
   "Supermicro"
]

fact (TrafficControl)

Description: The trafficcontrol interface is a special non-authenticated API for use by automation to POST system/device data to the CMDB without requiring any understanding of the resources or whether or not a resource already exists in the CMDB.

Request: POST /cmdb_api/v1/fact

Example:

environments TBD NEED MORE DOC

Descriptions: The environments API is a special hierarchal environments/services data API to facilitate a multi dimensional inherited data structure that was designed to be used for non-system service data. This was initially used to manage abstract data management of service configuration information to feed Puppet.

Request:

Example:

Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️