https://github.com/jas-/mlib-inventory-server
RESTFul API for management of computing inventory assets
https://github.com/jas-/mlib-inventory-server
Last synced: about 2 months ago
JSON representation
RESTFul API for management of computing inventory assets
- Host: GitHub
- URL: https://github.com/jas-/mlib-inventory-server
- Owner: jas-
- License: bsd-3-clause
- Created: 2013-08-02T19:42:59.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2014-05-06T14:55:45.000Z (about 11 years ago)
- Last Synced: 2025-01-28T14:47:09.093Z (4 months ago)
- Language: PHP
- Homepage:
- Size: 2.19 MB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
MLIB-Inventory-Server
=======================
Introduction
------------
Restful service for handling computer asset management.
Download
------------
It is best to clone this repo like so `git clone --recursive https://github.com/jas-/MLIB-Inventory-Server.git`
Installation
------------
To install simply run the `./install` file located within the 'install' folder
Virtual Host
------------
An example...
```
ServerName inventory.dev
DocumentRoot /var/www/html/MLIB-Inventory-Server/public
SetEnv APPLICATION_ENV "development"
DirectoryIndex index.php
AllowOverride All
Order allow,deny
Allow from all
ErrorLog /var/log/httpd/inventory_error
CustomLog /var/log/httpd/inventory_log common
```
MLIB-Inventory-Server RESTFul API
This document serves as a guide during installation, configuration
and implementation of the provided API for all asset record management
functionality.
This project works as the server component to the Marriott Library
Information Services inventory management service. The offical project
page can be found @ github.com/jas-/MLIB-Inventory-Server
Table of contents
- Project details
-
Download
-
Installation
-
API
-
Manage Model records
-
List all model records
-
Search model records
-
Add model records
-
Update model records
-
Delete model records
-
Manage Computer records
-
List all computer records
-
Search computer records
-
Add computer records
-
Update computer records
-
Delete computer records
-
Manage Monitor records
-
List all monitors records
-
Search monitor records
-
Add monitor records
-
Update monitor records
-
Delete monitor records
-
Manage RMA records
-
Manage CORS records
Project details ↑
The MLIB-Inventory-Server RESTFul API was developed to provide an
easy to use inventory asset management service. It does this by
providing an easy to implement API for any programming language
that supports the HTTP protocol.
Download ↑
This project allows for two methods of downloading, the GIT method
(recommended) or the manual method. Please read on for details of each.
Using GIT ↑
A git client is the prefered method of
installation as all dependencies will be setup and installed.
shell> git clone --recursive https://github.com/jas-/MLIB-Inventory-Server.git
Manual Installation ↑
Installing manually is not recommended however can be accomplished fairly
easily by downloading the source of this project @
MLIB-Inventory-Server.zip.
shell> unzip2 master.zip
Once you have downloaded the project you must extract it in a publicly
accessible area of your web server.
This project uses the Zend Framework which will need to be downloaded and
installed into the /path/to/MLIB-Inventory-Server/vendor/ZF2
folder. You can download the framework @
Zend Framework 2
Installation ↑
Once you have downloaded or used git to install the base files we will now
need to install the project.
Details ↑
Installation performs the following operations:
- New database creation
- New accounts:
- Administrative account (Read & Write privileges)
- Read Only account (Read only privileges)
- Database table creation
- Foreign key constraints for relational tables
- Views for non-authenticated use
- Stored procedures for all database operations
- Application configuration based on user input
Installation tool ↑
In order for the installation to be quite painless an installer is
included with the project. Please note that currently, becuase there is
only one version released that should be considered 'beta' no method
for updating database schema objects exists so you will want to ensure
a good working backup has been created prior to running the installer.
shell> bash install/install
Post installation ↑
Due to the cross origin resource sharing same origin restrictions if you
have setup the MLIB-Inventory (mobile web client) to access this
service you must add that URL to the whitelist (if installed on a
separate domain) to ensure proper functionality.
Using a stored procedure (created during the installation process), simply
issue the following command on the database.
shell> mysql -u <username> -p <dbname> -e 'CALL CorsAddUpdate("<appName>", "<FQDN>", "<IP>")'
API ↑
This API will allow management of records through a common end point per
record type.
Below is a list of the available end points and a description
of the record type.
Models ↑
Manage Models records. Below are the details of the available fields
per Models record. * Important: Computer, Monitor & RMA records all require an existing, matching model entry
-
Model - (Required) The model number associated with the montitor
-
Notes - (Optional) Any notes associated with the model
-
Description - (Optional) Any description information assocated with model
List models ↑
To list all available models:
GET /model
Response example:
[
{
"Id": "591",
"Model": "6200",
"Notes": "",
"Description": ""
},
{
"Id": "734",
"Model": "6350",
"Notes": "",
"Description": ""
},
/* ... */
]
Search models ↑
To search all available models (* is the wildcard):
GET /model/96*
Response example(s):
A successful response when searching for Models asset records
[
{
"id": "590",
"model": "965",
"description": "",
"notes": ""
},
/* ... */
]
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Generic error
{
error: 'Unable to search specified records'
}
Add models ↑
To add a new models:
POST /model
Serialized data (see required fields):
model=<model-number>
Response example(s):
A successful response when adding a Models asset record
{
success: 'Models record sucessfully add'
}
Invalid parameters response
{
"error": "Given parameters did meet validation requirements",
"details": {
"model": "Model value is invalid"
}
}
Generic error
{
error: 'Unable to add specified record'
}
Update models ↑
To update an existing Models record:
PUT /model/<record-id>
Serialized data (see required fields):
model=<model-number>&eowd=<eowd-date>&opd=<opd-date>
Response example(s):
A successful response when updating a Models asset record
{
success: 'Successfully updated record'
}
Invalid parameters response
{
"error": "Given parameters did meet validation requirements",
"details": {
"model": "Model value is invalid"
}
}
No changes occured message
{
warning: 'No changes to models record occured'
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting models record'
}
Generic error
{
error: 'Could not edit record'
}
Delete models ↑
Example usage of removing Models records.
Usage example ↑
To remove an existing models:
DELETE /model/<record-id>
Response example(s):
A successful response when removing a Models asset record
{
success: 'Successfully deleted record'
}
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting models record'
}
Generic error
{
error: 'Unable to delete specified record'
}
Computers ↑
Manage Computers records. Below are the details of the available fields
per Computers record.
-
Hostname - (Optional) The unique identifier associated with the computer
-
Model - (Optional) The model number associated with the montitor (see models)
-
SKU - (Required) The SKU number
-
UUIC - (Optional) The UUIC number
-
Serial - (Required) The serial number
-
EOWD - (Optional) The end of warranty date
-
OPD - (Optional) The original purchase date
-
Notes - (Optional) Any notes associated with the model
-
Description - (Optional) Any description information assocated with model
List computers ↑
To list all available computers:
GET /computer
Response example:
[
{
"Id": "1779",
"Hostname": "abc-123xyu123",
"Model": "965",
"SKU": "123",
"UUIC": "123",
"Serial": "123",
"EOWD": "2013-06-02",
"OPD": "2009-06-02",
"Notes": "",
"Description": ""
},
{
"Id": "1572",
"Hostname": "ACQ-01",
"Model": "6200",
"SKU": "017043",
"UUIC": "034755",
"Serial": "090705",
"EOWD": "2013-06-20",
"OPD": "2009-06-01",
"Notes": "",
"Description": ""
},
/* ... */
]
Search computers ↑
To search all available computers (* is the wildcard):
GET /computer/GRPC-1*
Response example(s):
A successful response when searching for Computers asset records
[
{
"Id": "1437",
"Hostname": "GRPC-10",
"Model": "970",
"SKU": "016058",
"UUIC": "040318",
"Serial": "087957",
"EOWD": "2013-06-02",
"OPD": "2009-06-02",
"Notes": "",
"Description": ""
},
{
"Id": "1452",
"Hostname": "GRPC-11",
"Model": "970",
"SKU": "016020",
"UUIC": "040280",
"Serial": "087933",
"EOWD": "2013-06-02",
"OPD": "2009-06-02",
"Notes": "",
"Description": ""
},
/* ... */
]
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Generic error
{
error: 'Unable to search specified records'
}
Add computers ↑
To add a new computers:
POST /computer
Serialized data (see required fields):
hostname=<computer-name>&model=<model-number>&sku=<computer-sku>&serial=<computer-serial>&eowd=<computer-eowd>&eopd=<computer-opd>¬es=<computer-notes>
Response example(s):
A successful response when adding a Computers asset record
{
success: 'Computers record sucessfully add'
}
Invalid parameters response
{
"error": "Given parameters did meet validation requirements",
"details": {
"hostname": "Hostname value is invalid",
"model": "Model value is invalid",
"sku": "SKU value is invalid",
"uuic": "UUIC value is invalid",
"serial": "Serial value is invalid",
"eowd": "EOWD value is invalid",
"opd": "OPD value is invalid",
"notes": "Notes value is invalid"
}
}
Generic error
{
error: 'Unable to add specified record'
}
Update computers ↑
To update an existing Computers record:
PUT /computers/<record-id>
Serialized data (see required fields):
hostname=<computer-name>&model=<model-number>&sku=<computer-sku>&serial=<computer-serial>&eowd=<computer-eowd>&eopd=<computer-opd>¬es=<computer-notes>
Response example(s):
A successful response when updating a Computers asset record
{
success: 'Successfully updated record'
}
Invalid parameters response
{
"error": "Given parameters did meet validation requirements",
"details": {
"hostname": "Hostname value is invalid",
"model": "Model value is invalid",
"sku": "SKU value is invalid",
"uuic": "UUIC value is invalid",
"serial": "Serial value is invalid",
"eowd": "EOWD value is invalid",
"opd": "OPD value is invalid",
"notes": "Notes value is invalid"
}
}
No changes occured message
{
warning: 'No changes to computers record occured'
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting computers record'
}
Generic error
{
error: 'Could not edit record'
}
Delete computers ↑
Example usage of removing Computers records.
Usage example ↑
To remove an existing computers:
DELETE /computers/<record-id>
Response example(s):
A successful response when removing a Computers asset record
{
success: 'Successfully deleted record'
}
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting computers record'
}
Generic error
{
error: 'Unable to delete specified record'
}
Monitors ↑
Manage Monitors records. Below are the details of the available fields
per Monitors record.
-
Hostname - (Optional) The unique identifier associated with the monitor
-
Model - (Optional) The model number associated with the montitor (see models)
-
SKU - (Required) The SKU number
-
Serial - (Required) The serial number
-
EOWD - (Optional) The end of warranty date
-
OPD - (Optional) The original purchase date
-
Notes - (Optional) Any notes associated with the model
-
Description - (Optional) Any description information assocated with model
List monitors ↑
To list all available monitors:
GET /monitor
Response example:
[
{
"Id": "478",
"Hostname": "GRPC-01",
"Model": "970",
"SKU": "16250",
"Serial": "ETLFA0W041115034C94323",
"EOWD": "2013-06-02",
"OPD": "2009-06-02",
"Notes": "",
"Description": ""
},
{
"Id": "491",
"Hostname": "GRPC-02",
"Model": "980",
"SKU": "16720",
"Serial": "ETLGQ0D053205019898514",
"EOWD": "2015-07-01",
"OPD": "2012-07-01",
"Notes": "",
"Description": ""
},
/* ... */
]
Search monitors ↑
To search all available monitors (* is the wildcard):
GET /monitor/GRPC-1*
Response example(s):
A successful response when searching for Monitors asset records
[
{
"Id": "480",
"Hostname": "GRPC-10",
"Model": "970",
"SKU": "16244",
"Serial": "ETLFA0W041113116544323",
"EOWD": "2013-06-02",
"OPD": "2009-06-02",
"Notes": "",
"Description": ""
},
{
"Id": "494",
"Hostname": "GRPC-11",
"Model": "970",
"SKU": "16252",
"Serial": "ETLFA0W041115034B14323",
"EOWD": "2013-06-02",
"OPD": "2009-06-02",
"Notes": "",
"Description": ""
},
/* ... */
]
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Generic error
{
error: 'Unable to search specified records'
}
Add monitors ↑
To add a new monitors:
POST /monitor
Serialized data (see required fields):
hostname=<monitor-name>&model=<model-number>&sku=<monitor-sku>&serial=<monitor-serial>&eowd=<monitor-eowd>&eopd=<monitor-opd>¬es=<monitor-notes>
Response example(s):
A successful response when adding a Monitors asset record
{
success: 'Monitors record sucessfully add'
}
Invalid parameters response
{
"error": "Given parameters did meet validation requirements",
"details": {
"hostname": "Hostname value is invalid",
"model": "Model value is invalid",
"sku": "SKU value is invalid",
"uuic": "UUIC value is invalid",
"serial": "Serial value is invalid",
"eowd": "EOWD value is invalid",
"opd": "OPD value is invalid",
"notes": "Notes value is invalid"
}
}
Generic error
{
error: 'Unable to add specified record'
}
Update monitors ↑
To update an existing Monitors record:
PUT /monitors/<record-id>
Serialized data (see required fields):
hostname=<monitor-name>&model=<model-number>&sku=<monitor-sku>&serial=<monitor-serial>&eowd=<monitor-eowd>&eopd=<monitor-opd>¬es=<monitor-notes>
Response example(s):
A successful response when updating a Monitors asset record
{
success: 'Successfully updated record'
}
Invalid parameters response
{
"error": "Given parameters did meet validation requirements",
"details": {
"hostname": "Hostname value is invalid",
"model": "Model value is invalid",
"sku": "SKU value is invalid",
"uuic": "UUIC value is invalid",
"serial": "Serial value is invalid",
"eowd": "EOWD value is invalid",
"opd": "OPD value is invalid",
"notes": "Notes value is invalid"
}
}
No changes occured message
{
warning: 'No changes to monitors record occured'
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting monitors record'
}
Generic error
{
error: 'Could not edit record'
}
Delete monitors ↑
Example usage of removing Monitors records.
Usage example ↑
To remove an existing monitors:
DELETE /monitors/<record-id>
Response example(s):
A successful response when removing a Monitors asset record
{
success: 'Successfully deleted record'
}
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting monitors record'
}
Generic error
{
error: 'Unable to delete specified record'
}
RMA ↑
Manage RMA records. Below are the details of the available fields
per RMA record.
-
Date - (Required) The date as YYYY-MM-DD
-
Hostname - (Required) The RMA hostname
-
Model - (Required) The model number (see models)
-
SKU - (Required) The SKU associated with the RMA
-
UUIC - (Optional) The UUIC associated with the RMA
-
Serial - (Required) The serial number associated with the RMA
-
Part - (Required) The part description
-
Notes - (Optional) Any additional notes associated with the RMA record
List rma ↑
To list all available rma:
GET /rma
Response example:
[
{
"Id": "1",
"Problem": "0",
"Date": "2014-04-15",
"Hostname": "DIG-15",
"Model": "6200",
"SKU": "017034",
"UUIC": "034746",
"Serial": "090722",
"Part": "Video",
"Notes": ""
},
{
"Id": "2",
"Problem": "1",
"Date": "2014-02-11",
"Hostname": "DIG-18",
"Model": "6200",
"SKU": "017037",
"UUIC": "034742",
"Serial": "090712",
"Part": "Motherboard",
"Notes": ""
},
/* ... */
]
Search rma ↑
To search all available rma (* is the wildcard):
GET /rma/2014-04-*
Response example(s):
A successful response when searching for RMA asset records
[
{
"Id": "1",
"Problem": "0",
"Date": "2014-04-15",
"Hostname": "DIG-15",
"Model": "6200",
"SKU": "017034",
"UUIC": "034746",
"Serial": "090722",
"Part": "Video",
"Notes": ""
},
/* ... */
]
Empty response
{
"error": "Whoopsie! No records found, perhaps a wildcard search may help (ex. computer-name*)"
}
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Generic error
{
error: 'Unable to search specified records'
}
Add rma ↑
To add a new rma:
POST /rma
Serialized data (see required fields):
hostname=<machine-name>&model=<model-number>&sku=<machine-sku>&uuic=<machine-uuic>&serial=<machine-serial>&part=<part-description>&description=<Description>
Response example(s):
A successful response when adding a RMA asset record
{
success: 'RMA record sucessfully add'
}
Invalid parameters response
{
"error": "Given parameters did meet validation requirements",
"details": {
"hostname": "Hostname value is invalid",
"model": "Model value is invalid",
"sku": "SKU value is invalid",
"uuic": "UUIC value is invalid",
"Serial": "Serial value is invalid",
"Part": "Part value is invalid",
"Description": "Description value is invalid",
}
}
Generic error
{
error: 'Unable to add specified record'
}
Update rma ↑
To update an existing RMA record:
PUT /rma/<record-id>
Serialized data (see required fields):
hostname=<machine-name>&model=<model-number>&sku=<machine-sku>&uuic=<machine-uuic>&serial=<machine-serial>&part=<part-description>&description=<Description>
Response example(s):
A successful response when updating a RMA asset record
{
success: 'Successfully updated record'
}
Invalid parameters response
{
"error": "Given parameters did meet validation requirements",
"details": {
"hostname": "Hostname value is invalid",
"model": "Model value is invalid",
"sku": "SKU value is invalid",
"uuic": "UUIC value is invalid",
"Serial": "Serial value is invalid",
"Part": "Part value is invalid",
"Description": "Description value is invalid",
}
}
No changes occured message
{
warning: 'No changes to rma record occured'
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting rma record'
}
Generic error
{
error: 'Could not edit record'
}
Delete rma ↑
Example usage of removing RMA records.
Usage example ↑
To remove an existing rma:
DELETE /rma/<record-id>
Response example(s):
A successful response when removing a RMA asset record
{
success: 'Successfully deleted record'
}
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting rma record'
}
Generic error
{
error: 'Unable to delete specified record'
}
CORS ↑
Manage CORS records. Below are the details of the available fields
per CORS record.
-
Application - (Required) The unique identifier associated with the
allowed application
-
URL - (Required) The FQDN of the referring application
-
IP - (Required) The IP of the referring application
List cors ↑
To list all available cors:
GET /cors
Response example:
[
{
"id": "1",
"application": "resource-name",
"url": "http://fqdn.of.resource-name",
"ip": "192.1.2.10"
},
{
"id": "2",
"application": "another-name",
"url": "http://fqdn.of.another-name",
"ip": "192.1.2.115"
},
/* ... */
]
Search cors ↑
To search all available cors (* is the wildcard):
GET /cors/resource*
Response example(s):
A successful response when searching for CORS asset records
[
{
"id": "1",
"application": "resource-name",
"url": "http://fqdn.of.resource-name",
"ip": "192.1.2.10"
},
/* ... */
]
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Generic error
{
error: 'Unable to search specified records'
}
Add cors ↑
To add a new cors:
POST /cors
Serialized data (see required fields):
application=<application-name>&url=<FQDN>&ip=<ip-address>
Response example(s):
A successful response when adding a CORS asset record
{
success: 'CORS record sucessfully add'
}
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
application: 'Application value is invalid'
url: 'URL value is invalid'
ip: 'IP value is invalid'
}
}
Generic error
{
error: 'Unable to add specified record'
}
Update cors ↑
To update an existing CORS record:
PUT /cors/<record-id>
Serialized data (see required fields):
application=<application-name>&url=<FQDN>&ip=<ip-address>
Response example(s):
A successful response when updating a CORS asset record
{
success: 'Successfully updated record'
}
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
application: 'Application value is invalid'
url: 'URL value is invalid'
ip: 'IP value is invalid'
}
}
No changes occured message
{
warning: 'No changes to cors record occured'
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting cors record'
}
Generic error
{
error: 'Could not edit record'
}
Delete cors ↑
Example usage of removing CORS records.
Usage example ↑
To remove an existing cors:
DELETE /cors/<record-id>
Response example(s):
A successful response when removing a CORS asset record
{
success: 'Successfully deleted record'
}
Invalid parameters response
{
error: 'Given parameters did meet validation requirements',
details: {
id: 'ID value is invalid'
}
}
Database record didn't exist
{
error: 'Whoops, an error occured while deleting cors record'
}
Generic error
{
error: 'Unable to delete specified record'
}