From OpenDCIM Wiki
Jump to: navigation, search
(Base URI)
Line 1: Line 1:
'''The API was added with release 4.0.1.  The wiki reflects the current status for the 4.2 release.'''
+
'''The API was added with release 4.0.1.  The wiki reflects the current status for the 20.01 release.'''
  
 
openDCIM has a RESTful API interface which can be accessed by other applications.
 
openDCIM has a RESTful API interface which can be accessed by other applications.
Line 5: Line 5:
 
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 [https://en.wikipedia.org/wiki/Representational_state_transfer Wikipedia Entry].
 
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 [https://en.wikipedia.org/wiki/Representational_state_transfer Wikipedia Entry].
  
 +
= openAPI/Swagger Documentation =
  
= Data Format =
+
We are actively building out openAPI/Swagger compliant documentation for the API.  Check out https://opendcim.org/demo/api/docs/ for the current documentation.  A few pieces of information will remain
 +
here on the wiki, but it will not be the authoritative source.
 +
 
 +
Starting with version 20.02, the Swagger API documentation is part of the openDCIM distribution and may be found at your $url/api/docs/
 +
 
 +
= Built-in Features for ALL Routes =
 +
 
 +
There isn't really a place in Swagger to denote this, but in nearly every route, you can pass any combination of property->value pairs (in JSON format) to filter based upon that combination.
 +
Additionally, if you pass the parameter 'wildcards' (with or without a value assigned) then the search will be performed with SQL standard wildcard symbols.  Finally, if you wish to only
 +
return a subset of attributes, send a comma separated list with the parameter name of 'attributes'.
 +
 
 +
POST routes are for modifying existing records - if you wish to retain the existing value for a property, simply do not pass it in your list.    We will only update the properties specified in your payload.
 +
 
 +
== 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.
 
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.
Line 21: Line 35:
  
  
= Authentication =
+
== 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.
 
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.
Line 59: Line 73:
  
 
API versions will not change often and are not the same as the openDCIM release version.  For example, the API has been at v1 since openDCIM version 4.0 and is still on v1 as of openDCIM version 4.3.  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/device
 
API versions will not change often and are not the same as the openDCIM release version.  For example, the API has been at v1 since openDCIM version 4.0 and is still on v1 as of openDCIM version 4.3.  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/device
 
= 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
 
 
In each of the object level GET requests, you can basically perform a search on any of the attributes of that particular object by specifying it in the URL.  Please note that Attribute names are case sensitive, so you should refer to the model for each object listed below in the wiki.
 
 
: '''Example''' To search for a Device object with the AssetTag of XYZ123, you would use the following URI:
 
 
<pre>
 
/api/v1/device?AssetTag=XYZ123
 
</pre>
 
 
You can also combine several attributes in your search.  For example, if you wanted to list all device objects that are in Cabinet 15 and have a DeviceType of Server, you could do the following:
 
 
<pre>
 
/api/v1/device?Cabinet=15&DeviceType=Server
 
</pre>
 
 
 
As of version 4.3, the API supports the ability to use Wildcards in your search patterns, using the % sign as the standard SQL wildcard.  To pass this to the API in a standard URL string, though, you have to escape it by writing a double % sign.  To enable wildcard searches, in addition to specifying a pattern you must also pass 'wildcards' (case insensitive) as a parameter.
 
 
: '''Example''' To do a wildcard search for all devices that contain the name 'test' you would do the following:
 
 
<pre>
 
/api/v1/device?wildcards&Label=%%test%%
 
</pre>
 
 
Also as of version 4.3, you can specify the list of Attributes to return on a search by passing a comma separated list of attributes in the URI.  '''Please note that attribute names are case sensitive''', so refer to the attribute listing in each of the object sections shown below.
 
 
: '''Example''' Building on the above query, let's say we only want to return the DeviceID and Label of the matches.
 
 
<pre>
 
/api/v1/device?wildcards&Label=%%test%%&attributes=DeviceID,Label
 
</pre>
 
 
= Sample Script =
 
 
Here you'll find a sample PHP script which utilizes the CURL library to make calls to the API.  The purpose of the script is to add a single user to the database.
 
 
<blockquote>
 
<pre>
 
<?php
 
        $c = curl_init();
 
        curl_setopt( $c, CURLOPT_URL, $url );
 
        curl_setopt( $c, CURLOPT_USERPWD, "dcim:dcim" );
 
        curl_setopt( $c, CURLOPT_CUSTOMREQUEST, "PUT" );
 
        curl_setopt( $c, CURLOPT_RETURNTRANSFER, true );
 
 
        // Following 2 lines are needed if you don't have a recognized CA certificate
 
        curl_setopt( $c, CURLOPT_SSL_VERIFYPEER, false );
 
        curl_setopt( $c, CURLOPT_SSL_VERIFYHOST, false );
 
 
        // Don't return the headers - we want the actual JSON data return
 
        curl_setopt( $c, CURLOPT_HEADER, false );
 
 
        // The lines below here are what you would put into a loop if you were wanting to proce
 
ss a bunch of files
 
        // Note that the URL has the new UserID added to it at the end - it is required
 
        $url = "https://dcim.mydomain/api/v1/people/newuser";
 
 
        $data = array(  "UserID" => "newuser",
 
                        "LastName" => "User",
 
                        "FirstName" => "API",
 
                        "Email" => "me@domain",
 
                        "AdminOwnDevices" => "1",
 
                        "ReadAccess" => "0",
 
                        "WriteAccess" => "0",
 
                        "DeleteAccess" => "0",
 
                        "ContactAdmin" => "0",
 
                        "RackRequest" => "0",
 
                        "RackAdmin" => "0",
 
                        "SiteAdmin" => "0" );
 
 
        $data_string = json_encode( $data );
 
 
        curl_setopt( $c, CURLOPT_POSTFIELDS, $data_string );
 
        curl_setopt( $c, CURLOPT_HTTPHEADER, array( "Content-Type: application/json", "Content-Length: " . strlen( $data_string )));
 
 
        $result = curl_exec( $c );
 
 
        $jr = json_decode( $result );
 
        // You really should check for errors here, for example just display output
 
        var_dump( $jr );
 
 
        // End of what you would have to run in a loop
 
 
        // Show the user what we got
 
 
        curl_close( $c );
 
?>
 
</pre>
 
</blockquote>
 
 
 
= 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 ==
 
 
[[APIPeople|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.
 
 
'''Data Structure''' (As of 4.3)
 
 
<nowiki>
 
{
 
    "error": false,
 
    "errorcode": 200,
 
    "people": [
 
        {
 
            "PersonID": 1,
 
            "UserID": "dcim",
 
            "LastName": "Admin",
 
            "FirstName": "DCIM",
 
            "Phone1": "",
 
            "Phone2": "",
 
            "Phone3": "",
 
            "Email": "scott@opendcim.org",
 
            "AdminOwnDevices": 1,
 
            "ReadAccess": 1,
 
            "WriteAccess": 1,
 
            "DeleteAccess": 1,
 
            "ContactAdmin": 1,
 
            "RackRequest": 1,
 
            "RackAdmin": 1,
 
            "SiteAdmin": 1,
 
            "Disabled": 0
 
        }
 
    ]
 
}
 
</nowiki>
 
 
== Department ==
 
 
[[APIDepartment|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 Structure''' (As of 4.3)
 
 
<nowiki>
 
{
 
    "error": false,
 
    "errorcode": 200,
 
    "department": [
 
        {
 
            "DeptID": "1",
 
            "Name": "Accounting",
 
            "ExecSponsor": "Scrooge McDuck",
 
            "SDM": "",
 
            "Classification": "Admin",
 
            "DeptColor": "#FFFFFF"
 
        }
 
    ]
 
}
 
</nowiki>
 
 
== Data Centers ==
 
 
[[APIDataCenter|Data Centers]] are parent structures for housing Cabinets, which can then house devices.
 
 
'''Data Structure''' (As of 4.3)
 
 
<nowiki>
 
{
 
    "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"
 
        }
 
    ]
 
}
 
</nowiki>
 
 
== Cabinets ==
 
 
[[APICabinet|Cabinets]] must belong to a Data Center, and contain devices, sensors, and CDUs.
 
 
'''Data Structure''' (As of 4.3)
 
 
<nowiki>
 
{
 
  "error": false,
 
  "errorcode": 200,
 
  "cabinet": [
 
    {
 
      "CabinetID": "21",
 
      "DataCenterID": "1",
 
      "Location": "AB04",
 
      "LocationSortable": "AB04",
 
      "AssignedTo": "0",
 
      "ZoneID": "0",
 
      "CabRowID": "0",
 
      "CabinetHeight": "42",
 
      "Model": "",
 
      "Keylock": "",
 
      "MaxKW": "0",
 
      "MaxWeight": "0",
 
      "InstallationDate": "2016-04-19",
 
      "MapX1": "0",
 
      "MapY1": "0",
 
      "MapX2": "0",
 
      "MapY2": "0",
 
      "FrontEdge": "Top",
 
      "Notes": "",
 
      "U1Position": "Bottom",
 
      "Rights": "Write",
 
      "DataCenterName": "DC1"
 
    }
 
  ]
 
}
 
</nowiki>
 
 
== 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.
 

Revision as of 19:01, 7 October 2020

The API was added with release 4.0.1. The wiki reflects the current status for the 20.01 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.

openAPI/Swagger Documentation

We are actively building out openAPI/Swagger compliant documentation for the API. Check out https://opendcim.org/demo/api/docs/ for the current documentation. A few pieces of information will remain here on the wiki, but it will not be the authoritative source.

Starting with version 20.02, the Swagger API documentation is part of the openDCIM distribution and may be found at your $url/api/docs/

Built-in Features for ALL Routes

There isn't really a place in Swagger to denote this, but in nearly every route, you can pass any combination of property->value pairs (in JSON format) to filter based upon that combination. Additionally, if you pass the parameter 'wildcards' (with or without a value assigned) then the search will be performed with SQL standard wildcard symbols. Finally, if you wish to only return a subset of attributes, send a comma separated list with the parameter name of 'attributes'.

POST routes are for modifying existing records - if you wish to retain the existing value for a property, simply do not pass it in your list. We will only update the properties specified in your payload.

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.

Apache Authentication

If you have enabled Apache Authentication for your site, you will need to pass login credentials with your API request the same as you would for any web request to the server. The Sample Script section below shows an example of passing the credentials in this manner.

This was the only mechanism available prior to version 4.2 of openDCIM.

LDAP Authentication

If you are running version 4.2 or later of openDCIM and have configured your system to work with LDAP Authentication, you will need to follow a few prerequisite steps.

  • Create a separate account in the openDCIM User Manager for the API access
  • Generate a key for the account
  • Pass the APIKey in the headers for all requests to the API

There are two custom headers that you must pass the information in:

  • UserID
  • APIKey

Header names are case sensitive, as are User IDs.

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)

API versions will not change often and are not the same as the openDCIM release version. For example, the API has been at v1 since openDCIM version 4.0 and is still on v1 as of openDCIM version 4.3. 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/device