Revision as of 21:34, 18 December 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/

If you are not serving openDCIM at the root of your DNS name, you will need to modify the basePath entry found in api/docs/swagger.yaml to match your path.

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