REST API V2

From IT Asset Management - Oomnitza Wiki
Revision as of 22:19, 24 February 2015 by Oomnitza (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The official documentation for the Oomnitza Platform API v2. This is a REST API with JSON structure.

Contents

Authorization

Basic authorization

The "basic" authentication scheme is based on the model that the client must authenticate itself with a user-ID and a password for each request. The server will service the request only if it can validate the user-ID and password for the protection space of the Request-URI. There are no optional authentication parameters.

Required header: Authorization This header should contain “Basic ” + your username and password with “:” as delimiter encoded in base64.

   Example (for username=username, password=password):
   Authorization = Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Token authorization

Requesting token

This service client should call once during authorization. It validates user credentials and provides token if everything is OK. Otherwise, client will get 401 error.

   URL: /api/v2/request_token
   Method: GET 
   Parameters:
   •	login – user login
   •	password – user password
   Response (Success):
   {"token": "4239599e8ce542c28d1qf053bdd23428"}

Using token

Every request should contain Authorization2 header with token.

Revoking token

This service client should call this to revoke an existing token:

   URL: /service/logout
   Method: GET 
   Parameters:
   •	access_token – token to invalidate
   Response (Success):
   {"errors": []}

Workstream Management

Getting messages

   URL: /api/v2/messages
   Method: GET 
   Parameters:
   •	limit – optional, maximum number of messages in response, default 100
   •	offset– optional, number of messages needed to skip, default 0
Response (Success):
[{
    "files": [{
        "thumbnail": "https://client.oomnitza.com/media/attachments/2?thumbnail=100",
        "type": "JPG",
        "id": 2,
        "data": "https://client.oomnitza.com/media/attachments/2",
        "name": "file_1"
    }],
    "recipients": [{
        "type": 0,
        "id": 1,
        "title": "User1"
    }],
    "object": {
        "type": "Equipment",
        "id": "1725"
    },
    "message": "Loan Status Changed",
    "id": 37,
    "seconds_ago": 44225,
    "from": {
        "thumbnail": "https://client.oomnitza.com/media/user/user1?thumbnail=100",
        "data": "https:// client.oomnitza.com/media/user/user1",
        "id": "user1",
        "name": "First User"
    },
    "forward_possible": false,
    "decision": {
        "available": false,
        "finished": false,
        "who": {
            "comment": "",
            "decision": "REJECT",
            "when": 1395310029,
            "id": "user2",
            "name": "User 2"
        }
    },
    "comments": 10,
    "created_at": 1397687366
}]

Creating messages

   URL: /api/v2/messages
   Method: POST
   Parameters: None
Request body:
{
    "message": "Lorem ipsum dolor sit...",
    “lat”: 0,
    “long”: 0,
    "recipients": {
        "roles": [],
        "users": [
            "user1"
        ]
    }
}
Response (Success):
{'id':  12312}

Getting comments

   URL: /api/v2/messages/16/comments
   Method: GET 
   Parameters: None
Response (Success):
[{
    "files": [], 
    "seconds_ago": 2818400, 
    "from": {
        "thumbnail": " https://client.oomnitza.com/media/user/user1?thumbnail=100", 
        "data": " https://client.oomnitza.com /media/user/user1", 
        "id": "user1", 
        "name": "User 1"
    }, 
    "created_at": 1395341785, 
    "message": "Test Comment", 
    "id": 5
}]

Creating comments

   URL: /api/v2/messages/{ID}/comments
   Method: POST
   Parameters: None
Request body: 
{
    "message": "Lorem ipsum dolor sit...",
    "lat": 0,
    "long": 0
}
Response (Success):
{'id':  12312}

Creating media for message

   URL: /api/v2/messages/{ID}/media
   Method: POST
   Parameters: None
   Request body: Binary
Response (Success):
{'id':  12312}

Creating media for comment

   URL: /api/v2/messages/{ID}/comments/media
   Method: POST
   Parameters: None
   Request body: Binary
Response (Success):
{'id':  12312}

Forwarding message

   URL: /api/v2/messages/{ID}/forward
   Method: PUT
   Parameters: None
   Request body: None
Response (Success):''' OK</span>

Sharing message

   URL: /api/v2/messages/{ID}/forward
   Method: PUT
   Parameters: None
Request body: 
{
    “users”: [“anton”, “peter”],
    “roles”: [“manager”]
}
Response (Success): OK

Approve message

   URL: /api/v2/messages/{ID}/approve
   Method: PUT
   Parameters: None
Request body: 
{
    “comment”: “Hi There!”
}
Response (Success): OK

Reject message

   URL: /api/v2/messages/{ID}/reject
   Method: PUT
   Parameters: None
Request body: 
{
    “comment”: “Hi There”
}
Response (Success): OK

Asset Management

Getting asset

   URL: /api/v2/assets/{ID}
   Method: GET
   Parameters: None
   Request body: None
Response (Success):
{
    "19395C94061D11E3A473525400385B84": 0,
    "EQUIPMENTID": "bc69ccbaa8d811e3af92525400586e1c",
    "VERSION": "0",
    "CREATEDBY": " user1",
    "id": 1468,
    "MANUFACTURER": "Kelloggs",
    "CHANGEDBY": "user1",
    "ATTACHMENTS_COUNT": 1,
    "NAME": "Poptarts",
    "LOCATION": "947",
    "CREATIONDATE": "1394513457",
    "CHANGEDATE": "1394513457",
}

Getting list of asset media

   URL: /api/v2/assets/{ID}/media
   Method: GET
   Parameters: None
   Request body: None
Response (Success):
[{
    "description": "file_0",
    "type": "JPG",
    "name": "file_0",
    "id": 411
}]

Getting media (full)

   URL: /api/v2/assets/{ID}/media/{MEDIA_ID}
   Method: GET
   Parameters: None
   Request body: None
Response (Success): Binary

Getting media (thumbnail)

   URL: /api/v2/assets/{ID}/media/{MEDIA_ID}/thumbnail
   Method: GET
   Parameters: None
   Request body: None
Response (Success): Binary

Creating assets

Creating asset fields

   URL: /api/v2/assets
   Method: POST
   Parameters: None
Request body: 
{
    "D8A1FD6062D511E39C43525400385B84": "Test",
    "F33B42BC62D511E3A2E2525400385B84": "Test2",
    "MANUFACTURER": "Kellogs",
    "BARCODE": "",
    "NAME": "Nam",
    "DATEBOUGHT": "",
    "LOCATION": "947",
    "LASTMAINTENANCE": "",
    "ATTACHMENTS_COUNT": 0,
}
Response (Success):
{
    "D8A1FD6062D511E39C43525400385B84": “Test”,
    "F33B42BC62D511E3A2E2525400385B84": “Test2,
    "EQUIPMENTID": "bc69ccbaa8d811e3af92525400586e1c",
    "VERSION": "0",
    "CREATEDBY": "user1",
    "id": 1468,
    "MANUFACTURER": "Kelloggs",
    "CHANGEDBY": " user1",
    "ATTACHMENTS_COUNT": 1,
    "NAME": "Poptarts",
    "LOCATION": "947",
    "CREATIONDATE": "1394513457",
    "CHANGEDATE": "1394513457",
}

Attach media (optional)

   URL: /api/v2/assets/{ID}/media
   Method: POST
   Parameters: None
   Request body: Binary
Response (Success):
{“id”: 12345}

Finalize asset creation

   URL: /api/v2/assets/{ID}/finalize
   Method: POST
   Parameters: None
   Request body: None
Response (Success): OK

Searching asset

   URL: /api/v2/assets
   Method: GET 
   Parameters:
   •	limit – optional, maximum number of messages in response, default 100
   •	offset– optional, number of messages needed to skip, default 0
   •	{FIELD_ID} – search criteria for certain field
Response (Success):
[{
    " D8A1FD6062D511E39C43525400385B84": “Test”,
    " F33B42BC62D511E3A2E2525400385B84": “Test2,
    "EQUIPMENTID": "bc69ccbaa8d811e3af92525400586e1c",
    "VERSION": "0",
    "CREATEDBY": "user1",
    "id": 1468,
    "MANUFACTURER": "Kelloggs",
    "CHANGEDBY": " user1",
    "ATTACHMENTS_COUNT": 1,
    "NAME": "Poptarts",
    "LOCATION": "947",
    "CREATIONDATE": "1394513457",
    "CHANGEDATE": "1394513457",
}]

Editing asset

Edit asset properties

   URL: /api/v2/assets/{ID}
   Method: PUT
   Parameters: None
Request body: 
{
    "D8A1FD6062D511E39C43525400385B84": "new value",
    "F33B42BC62D511E3A2E2525400385B84": "new value2",
}
Response (Success):
{
    "D8A1FD6062D511E39C43525400385B84": “new value”,
    "F33B42BC62D511E3A2E2525400385B84": “new value2,
    "EQUIPMENTID": "bc69ccbaa8d811e3af92525400586e1c",
    "VERSION": "0",
    "CREATEDBY": "user1",
    "id": 1468,
    "MANUFACTURER": "Kelloggs",
    "CHANGEDBY": " user1",
    "ATTACHMENTS_COUNT": 1,
    "NAME": "Poptarts",
    "LOCATION": "947",
    "CREATIONDATE": "1394513457",
    "CHANGEDATE": "1394513457",
}

Copying media from asset (optional)

   URL: /api/v2/assets/{ID}/copy_media
   Method: GET
   Parameters: 
        to – asset target id
   Request body: None
Response (Success): OK

Editing media (optional)

   URL: /api/v2/assets/{ID}/media/{MEDIA_ID}
   Method: PUT
   Parameters: None
Request body: 
{
    “name”: “Test”,
    “description”: “Test2”
}
Response (Success): "" (empty string)

Deleting media (optional)

   URL: /api/v2/assets/{ID}/media/{MEDIA_ID}
   Method: DELETE
   Parameters: None
   Request body:  None
Response (Success): {“id”: 1234}

Finalize editing an asset

Same process as above (see Finalize asset creation)

Copying assets

To copy asset client should just create new asset based on fields and values from old one, then if it needed copy/edit/delete media for it. And at last – finalize process

Report Management

Creating report

Create report fields and save attached assets

   URL: /api/v2/reports
   Method: POST
   Parameters: None
Request body: 
{
    "TITLE": "Test",
    "DESCRIPTION": "",
    “assets”: [1,2,3]
}
Response (Success):
{
    "assets": [1,2,3],
    "TITLE": "Test",
    "ATTACHMENTS_COUNT": 1,
    "id": 1,
    "DESCRIPTION": ""
}

Uploading media to report

   URL: /api/v2/reports/{ID}/media
   Method: POST
   Parameters: None
   Request body: Binary
Response (Success): {"id": 12345}

Finalizing report creation

   URL: /api/v2/reports/{ID}/finalize
   Method: POST
   Parameters: None
   Request body: None
Response (Success): OK

Getting media list for report

   URL: /api/v2/reports/{ID}/media
   Method: GET
   Parameters: None
   Request body: None
Response (Success):
[{
    "description": "file_0",
    "type": "JPG",
    "name": "file_0",
    "id": 1
}]

Getting report

   URL: /api/v2/reports/{ID}
   Method: GET
   Parameters: None
   Request body: None
Response (Success):
{
    "assets": [1,2,3],
    "TITLE": "Test",
    "ATTACHMENTS_COUNT": 1,
    "id": 1,
    "DESCRIPTION": ""
}

Getting media (full)

   URL: /api/v2/ reports /{ID}/media/{MEDIA_ID}
   Method: GET
   Parameters: None
   Request body: None
Response (Success): Binary

Getting media (thumbnail)

   URL: /api/v2/reports/{ID}/media/{MEDIA_ID}/thumbnail
   Method: GET
   Parameters: None
   Request body: None
Response (Success): Binary

User Management

Getting users

   URL: /api/v2/users
   Method: GET
   Parameters: 
   •	limit – optional, maximum number of messages in response, default 100
   •	offset– optional, number of messages needed to skip, default 0
   Request body: None
Response (Success):
[{
    "id": "user2",
    "value": "User Name2"
}, {
    "id": "user1",
    "value": "User Name1"
}, {
    "id": "user3",
    "value": "User Name3"
}]

Getting certain user

   URL: /api/v2/users/{ID}
   Method: GET
   Parameters: None
   Request body: None
Response (Success):
 {
    "FIRST_NAME": "User",
    "LAST_NAME": "Name1",
    "USER": "user1"
}

Creating a user

   URL: /api/v2/users
   Method: POST
   Parameters: None
Request body: 
{
    "USER": "tom.berry",
    "FIRST_NAME": "Tom",
    "LAST_NAME": "Barry",
    "PASSWORD": "mysecretpassword",
    "EMAIL": "tom.barry@co.com",
    "PERMISSIONS_ID": "1",
    "POSITION": "Engineering Manager"
}
Response (Success):
{
    "USER": "tom.berry",
    "FIRST_NAME": "Tom",
    "LAST_NAME": "Barry",
    "PASSWORD": "***",
    "EMAIL": "tom.barry@co.com",
    "PERMISSIONS_ID": "1",
    "POSITION": "Engineering Manager",
    "GPS_LAT": null,
    "GPS_LNG": null,
    "PHONE": "",
    "LOCATION": null,
    "ADDRESS": ""
}

Editing a user

   URL: /api/v2/users/{USER}
   Method: POST
   Parameters: None
Request body: 
{
    "FIRST_NAME": "Tommy",
    "PASSWORD": "mynewpassword",
    "EMAIL": "tom.barry@co.com"
}
Response (Success):
{
    "USER": "tom.berry",
    "FIRST_NAME": "Tommy",
    "LAST_NAME": "Barry",
    "PASSWORD": "***",
    "EMAIL": "tom.barry@co.com",
    "PERMISSIONS_ID": "1",
    "POSITION": "Engineering Manager",
    "GPS_LAT": null,
    "GPS_LNG": null,
    "PHONE": "",
    "LOCATION": null,
    "ADDRESS": ""
}

Field Management

Getting all fields

   URL: /api/v2/fields
   Method: GET
   Parameters:  None
   Request body: None
Response (Success):
[{
    is_autocomplete: false,
    default: "",
    length: 20,
    is_optional: false,
    possible_options: null,
    label: "Field Label",
    type: "CHAR",
    id: 19,
    tech_id: "FIELD_TECH_ID"
}, ...]

Getting all asset fields

   URL: /api/v2/fields/assets
   Method: GET
   Parameters:  None
   Request body: None
Response (Success):
[{
    is_autocomplete: false,
    default: "",
    length: 20,
    is_optional: false,
    possible_options: null,
    label: "Barcode",
    type: "CHAR",
    id: 19,
    tech_id: "BARCODE"
}, ...]

Getting all location fields

   URL: /api/v2/fields/locations
   Method: GET
   Parameters:  None
   Request body: None
Response (Success):
[{
    is_autocomplete: false,
    default: "",
    length: 20,
    is_optional: false,
    possible_options: null,
    label: "Location ID",
    type: "CHAR",
    id: 19,
    tech_id: "LOCATION_ID"
}, ...]

Location Management

Getting locations

Getting by GPS coordinates

   URL: /api/v2/locations
   Method: GET
   Parameters: 
   •	selected_id – ID of assets that we don’t need to include into cluster
   •	limit – optional, only if clustering isn’t supported, maximum number of messages in response, default 100
   •	offset– optional, only if clustering isn’t supported, number of messages needed to skip, default 0
   •	lat – latitude left min (works if clustering is not enabled)
   •	lng – longitude (works if clustering is not enabled)
   •	vp_x_min – left min (works if clustering is enabled)
   •	vp_y_min – top min (works if clustering is enabled)
   •	vp_x_max – left max (works if clustering is enabled)
   •	vp_y_max – top max (works if clustering is enabled)
   Request body: None
Response (Success):
[{
    "properties": {},
    "stored": "0",
    "facility": "94508",
    "lat": "0.0",
    "lng": "0.0",
    "total": "None",
    "id": "94508",
    "address": "94508",
    "label": "056751-1 BAR DE LA PLAZA"
}]

Getting by search criteria

   URL: /api/v2/locations
   Method: GET
   Parameters: 
   •	search_query – search criteria
   Request body: None
Response (Success):
[{
    "lat": 45.5330544,
    "lng": -73.7514954,
    "id": "93941",
    "label": "8567521 DEPANNEUR SAMSON"
}]

Getting certain location

   URL: /api/v2/locations/{ID}
   Method: GET
   Parameters: None
   Request body: None
Response (Success):
{
    lat: 45.5330544
    lng: -73.7514954
    id: "93941"
    label: "8567521 DEPANNEUR SAMSON"
}

Additional Services

Getting users and roles

   URL: /api/v2/users_roles
   Method: GET
   Parameters: None
   Request body: None
Response (Success):
[{
    "type": "user",
    "id": "user2",
    "value": "User Name2"
}, {
    "type": "user",
    "id": "user1",
    "value": "User Name1"
}, {
    "type": "user",
    "id": "user3",
    "value": "User Name3"
},{
    "type": "role",
    "id": "38",
    "value": "Standard"
}]