From OpenDCIM Wiki
Revision as of 11:05, 23 December 2015 by Scott (Talk | contribs)

Jump to: navigation, search

The API was added with release 4.0.1. The wiki reflects the current status for the 4.1 release.

openDCIM has a RESTful API interface which can be accessed by other applications.

Development of the API is happening in stages, and as such this specification is subject to change. If you are unfamiliar with what a RESTful API is, a good place to start is the Wikipedia Entry.


Data Format

openDCIM data will always be returned in JSON format, with no pagination. This is open source, so if you need your output in another format, such as XML, you can modify the appropriate function in the application.

The JSON data is returned in the following format:

{

error: true or false,
errorcode: 200, if operation was a success; other dependent upon reason for failure
resultsetname (Varies depending upon request)
[{ data }]

}


Authentication

RESTful APIs by definition are stateless, but do still need some form of authentication. It is suggested that you create a separate account for the API to use, rather than piggy-backing off of an existing user account.

At a minimum, the account created for the API must have Global Read Access. Working with the inner guts of openDCIM will certainly increase the risk of data corruption, so it's not something that should be opened up lightly. If an API call requires a Specific Permission and is called by an account that does not possess that permission, an error 400 will be returned.

Base URI

Depending on how you implement your website, this may vary, but most would take on the format of:

https://myurl/api/v1 (for Version 1 of the API)

All definitions listed below will assume that they are added on to the base URI. For example, to get a list of all devices, the full URI would be https://myurl/api/v1/devices

Conventions

When listing a URI for an API call, there may occasionally be a word with a leading colon (:). This indicates that it is a parameter to be passed within the URL.

Example :deviceid would be the indication to substitute the last portion of the URL with a valid DeviceID


Structures

Below are the data structures that can be references and/or modified through use of the API. Detailed information on the API methods are available within the individual pages. In some cases, methods may be referenced in more than one location.

People

People refers to the entity that encompasses both users of openDCIM and the contacts that are associated with devices. Prior to version 4.x these were two separate entities, but due to the confusion around when to use which, they were merged into a single database table.

Department

Department refers to the entity in openDCIM that is assigned ownership of devices and cabinets. We restrict the ownership to departments because people are transitory - even if they don't leave the company, they can often change duties, while departments are much more static.


Data Centers

{
    "error": false,
    "errorcode": 200,
    "datacenter": [
        {
            "DataCenterID": "1",
            "Name": "Main DC",
            "SquareFootage": "2000",
            "DeliveryAddress": "1 Main Street",
            "Administrator": "Bobby Tables",
            "MaxkW": "1250",
            "DrawingFileName": "maindc.png",
            "EntryLogging": "0",
            "dcconfig": null,
            "ContainerID": "1",
            "MapX": "318",
            "MapY": "628",
            "U1Position": "Default"
        }
    ]
}
/datacenter
Method GET
Parameters none
Specific Permission Required none

This URI will return a collection of all data centers defined within openDCIM. There is a corresponding Entity URL for retrieving a single entity.

Cabinets

{
    "error": false,
    "errorcode": 200,
    "cabinet": [
        {
            "CabinetID": "578",
            "DataCenterID": "7",
            "Location": "E102.AJ48",
            "LocationSortable": "E102.AJ48",
            "AssignedTo": "3",
            "ZoneID": "9",
            "CabRowID": "13",
            "CabinetHeight": "50",
            "Model": "DDN",
            "Keylock": "",
            "MaxKW": "14.4",
            "MaxWeight": "2500",
            "InstallationDate": "2013-05-23",
            "MapX1": "696",
            "MapY1": "179",
            "MapX2": "729",
            "MapY2": "204",
            "FrontEdge": "Left",
            "Notes": "",
            "U1Position": "Bottom",
            "Rights": "Write",
            "DataCenterName": "5600 E102"
        }
    ]
}
/cabinet
Method GET
Parameters none
Specific Permission Required none

This URI will return a collection of all cabinets defined within openDCIM. There is a corresponding Entity URL for retrieving a single entity.


/cabinet/bydc/:datacenterid
Method GET
Parameters DataCenterID
Specific Permission Required none

This URI will return a collection of all cabinets, if any, that are defined within openDCIM as belonging to the specified DataCenterID.


/cabinet/bydept/:departmentid
Method GET
Parameters DepartmentID
Specific Permission Required none

This URI will return a collection of all cabinets, if any, that are defined within openDCIM as belonging to the specified DepartmentID.

Devices

/device
Method GET
Parameters none
Specific Permission Required none

This URI will return a collection of all devices defined within openDCIM. There is a corresponding Entity URL for retrieving a single entity.


/device/byowner/:departmentid
Method GET
Parameters DepartmentID
Specific Permission Required none

This URI will return a collection of all devices, if any, that are defined within openDCIM as belonging to the specified DepartmentID.

/device/bydatacenter/:datacenterid
Method GET
Parameters DataCenterID
Specific Permission Required none

This URI will return a collection of all devices, if any, that are defined within openDCIM as belonging to the specified DataCenterID.


/device/bycabinet/:cabinetid
Method GET
Parameters CabinetID
Specific Permission Required none

This URI will return a collection of all devices, if any, that are defined within openDCIM as belonging to the specified CabinetID.

Elements

Elements are API requests where a single entity is acted upon. As these are always acting upon just one tuple of the database, some of the API calls may be for creating, updating, or deleting data.

People

/people/:personid
Method GET
Parameters personid
Specific Permission Required Contact Administrator

This URI will return a single row matching the specified personid if it exists within the database, or an error if not found.


Data Centers

/datacenter/:datacenterid
Method GET
Parameters datacenterid
Specific Permission Required none

This URI will return a single row matching the specified DataCenterID if it exists within the database, or an error 404 if not found.

Cabinets

/cabinet/:cabinetid
Method GET
Parameters CabinetID
Specific Permission Required none

This URI will return a single row matching the specified CabinetID if it exists within the database, or an error 404 if not found.

Devices

/device/:deviceid
Method GET
Parameters DeviceID
Specific Permission Required none

This URI will return a single row with the specified DeviceID as key it it exists within the database, or an error 404 if not found.

/device/:deviceid/getpicture
Method GET
Parameters DeviceID
Specific Permission Required none

This URI will return an HTML formatted div for the picture of the device.

/device/:deviceid/getsensorreadings
Method GET
Parameters DeviceID
Specific Permission Required none

This URI will return a special object type as such.

Retrieved from "https://wiki.opendcim.org/wiki/index.php?title=API&oldid=1091"