-
Notifications
You must be signed in to change notification settings - Fork 208
API
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.
We are actively building out openAPI/Swagger compliant documentation for the API. Check out https://demo.opendcim.org/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.
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.
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 }]
}
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.
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.
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.
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