OneCMDB HTTP API V2.0

From OneCMDB

Contents

HTTP API V2.0

Overview

The easiest way to start interact with OneCMDB is to use the HTTP API. It is a URL based API,
where all operations are performed through URL's. To get an understanding of the model and
concepts used in this manual, read OneCMDB Concepts first.

A complete php example, that uses the Basic Model and demo instances, is located here: HTTP API - PHP Exmaple

Commands

The following commands are available:

  • auth
    • Authenticates a user. The result will be a token that has to be passed along with the other commands.
  • query
    • Fetch data from OneCMDB. It’s always a read-only operation.
  • update
    • Update data in OneCMDB.
  • create
    • Create data in OneCMDB.
  • delete
    • Delete data in OneCMDB.

The URL to access service(s) is as follows:

http://host:port/onecmdb/remote/http/cmd?option1&option2…&optionN

XPath - XML Path Language

The HTTP API uses the xpath language to locate objects. XPath is a W3C standard for querying XML documents. See http://en.wikipedia.org/wiki/XPath for more information about XPath. The path option, see below, is expressed using xpath syntax.

Auth Command

Must be performed first if authentication is enabled in OneCMDB. The token returned is needed for all subsequent query/update/delete commands. Options:

  • user=’username’
    • The user name to login as.
  • pwd=’password’
    • The password for the user name.

Example Request:

	http://localhost:8080/remote/http/auth?user=admin&pwd=123

Response:

	X6g4

Query Command

Options:

  • auth=’token’
    • The token received by an earlier auth command.
  • path=’XPath expression’
    • Filter out object(s) to receive.
  • ouputAttributes=’expr1 expr2 … exprN’
    • A set of xpath expressions that specify which attributes to receive from the selected objects specified by the path option. If omitted the attribute ‘displayName’ is returned for the objects. If all attributes are to be returned use *.
      • Internal attributes are
        • alias
        • id
        • derivedFrom
        • description
        • created (Available in patch)
        • lastModified (Available in patch)
        • displayName
        • displayNameExpression
  • outputFormat=’property|csv|xml’
    • How the response shall be formatted.

Examples

List all routers

Request:

http://localhost:8080/remote/http/query?auth=x6g4&path=/instance/Router/*&outputFormat=xml

Respons as XML:

<?xml version="1.0" encoding="UTF-8"?>
<onecmdb>
        <instances>
                <Router alias="R1">
                        Router 192.168.1.1 at Site Danderyd
                </Router>
                <Router alias="R2">
                        Router 192.168.1.2 at Site Solna
                </Router>
        </instances>
</onecmdb>

The value returned is the evaluated display name for each router.

Find a router with a specific alias

Request:

http://localhost:8080/remote/http/query?auth=x6g4&path=/instance/Router/R1&outputFormat=xml

Respons as XML:

<?xml version="1.0" encoding="UTF-8"?>
<onecmdb>
        <instances>
                <Router alias="R1">
                        Router 192.168.1.1 at Site Danderyd
                </Router>
        </instances>
</onecmdb>

List all routers primaryIp and site attributes, return as csv

Request:

http://localhost:8080/remote/http/query?
auth=x6g4&
path=/instance/Router/*&
outputAttributes=primaryIp%20site/name&
outputFormat=csv

Response in CSV

/instance/Router/*/primaryIp;/instances/Router/*/site/name
192.168.1.1;Solna
192.168.1.2;Danderyd

Find a router from its primaryIp, return as csv

http://localhost:8080/remote/http/query?
auth=x6g4&
path=/instance/Router/*[primaryIp/asString='192.168.1.1’]&
outputAttributes=primaryIp%20site/name&
outputFormat=csv

Response in CSV

/instance/Router/*/primaryIp;/instances/Router/*/site/name
192.168.1.1;Solna

Get routers ip address that a certain Person is responsible for

Request:

http://localhost:8080/remote/http/query?
auth=x6g4&
path=/instance/Router/*[site/supervisor/name=”Sven”]&
outputAttributes=primaryIp site/supervisor/name&
outputFormat=xml

Response as XML:

<?xml version="1.0" encoding="UTF-8"?>
<onecmdb>
        <instances>
                <Site alias="S1">
                        Site Danderyd
                        <supervisor><ref alias="Anna"/></supervisor>
                        <supervisor><ref alias="Sven"/></supervisor>
                </Site>
                <Person alias="Anna">
                        Person Anna Svensson
                        <name>Anna Svensson</name>
                </Person>
                <Person alias="Sven">
                        Person Sven Svensson
                        <name>Sven Svensson</name>
                </Person>
                <Router alias="R1">
                        Router 192.168.1.1 at Site Danderyd
                        <site><ref alias="S1"/></site>
                        <primaryIp>192.168.1.1</primaryIp>
                </Router>
        </instances>
</onecmdb>

Response as property:

Router.R1.primaryIp=192.168.1.1
Router.R1.site.supervisor.name[0]=Anna Svensson
Router.R1.site.supervisor.name[1]=Sven Svensson

Response as CSV.

/instance/Router/*[site/supervisor/alias="Sven"]/primaryIp;/instance/Router/*[site/supervisor/alias="Sven"]/site/supervisor/name
192.168.1.1;Anna Svensson,Sven Svensson

Update Command

  • Auth=’token’
    • The token received by an earlier auth command.
  • Path=’XPath expression’
    • Filter out object(s) to receive.
  • InputAttributes=’attribute=value;… ;attributeN=valueN’
    • A set of attributes and values. Delimited by ';'

Examples

Modify person Sven's telephone number

Request:

http://localhost:8080/remote/http/update?
auth=x6g4&
path=/instance/Person/Sven&
inputAttributes=telephone=070-657388576&

Responses:

HTTP status 200 if ok

HTTP status 404 if not found

Connect a Router instance to a Site and Site to Person

Request:

http://localhost:8080/remote/http/update?
Auth=x6g4&
Path=/instance/Router/R1&
InputAttributes=site=[/instance/Site/S1];site/supervisor=[/instance/People/Sven]&

Create Command

  • Auth=’token’
    • The token received by an earlier auth command.
  • Path=’XPath expression’
    • A new path that does not exist.
  • InputAttributes=’attribute=value; … ;attributeN=valueN’
    • A set of attributes and values. Delimited by ';'

Create a new person instance

Note: The Person will be created with alias = 'Peter' as specified in the path. This alias must be unique or else an error will be returned. Request:

http://localhost:8080/remote/http/create?
Auth=x6g4
Path=/instance/Person/Peter
InputAttributes=name=Peter Svensson;email=peter@acme.com&

Delete Command

  • auth='token'
    • The token received by an earlier auth command.
  • path
    • The path to the object(s) to delete.

Examples

Delete Person 'Sven' from OneCMDB

Request:

http://localhost:8080/remote/http/delete?
Auth=x6g4&
Path=/instance/People/Sven
Community and support