Skip to content

API

Jump to bottom
Isaac Finnegan edited this page Dec 3, 2013 · 28 revisions

Intro

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

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

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

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

Creating

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. Example: curl -v -uusername:password http://localhost/cmdb_api/v1/system/ \ -d'{"fqdn":"test3.example.com","ipaddress":"10.10.10.12","macaddress":"00:16:3e:00:4e:98"}'

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

 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
Clone this wiki locally