Web API Requests
On this page:
GET Methods
POST and PUT Methods
Retrieving individual resources
To retrieve a specific resource you can append its identifier to the end of the URL. The example below shows retrieving a specific contact using the HTTP GET method.
Example 1: To retrieve the Asset with the PK of "1":
https://{api-url}/v7/assets/1
- Successful responses return with a HTTP 200 status code
- By default all successful API responses are returned as JSON
Retrieving a filtered set of resources
Filters can be added to any GET request by appending an OData style $filter querystring to the end of the request URI.
Currently OData support is limited to the following keywords:
| Operator | Description |
|---|---|
| Logical Operators | |
| eq | equal |
| ne | not equal |
| gt | greater than |
| ge | greater than or equal |
| lt | less than |
| le | less than or equal |
| and | logical and |
| or | logical or |
| not | logical negation |
| Grouping Operators | |
| ( ) | precedence grouping |
The $filter parameter can reference any element in the resulting response including those nested in "Ref" type elements such as "RepairCenterRef.ID".
Example 1: To retrieve all Work Orders in the Main Repair Center the following filter could be used on the WorkOrders resource:
https://{api-url}/v7/workorders?$filter=RepairCenterRef.ID%20eq%20"Main"
https://{api-url}/v7/assets?$filter=LastModifiedDate%20gt%20"2012-10-15"
https://{api-url}/v7/assets?$filter=IsOpen%20eq%20true%20and%20TargetHours%20lt%5
Paging through result sets
By default, GET requests to the Web API will return a page containing the top 50 matching results. This can be extended to a maximum of 500 results by appending an OData style $top querystring to the end of the request URI. Paging through result sets is done through the use of the $skip keyword.
Example 1: To retrieve the 3rd page of Work Orders in the "Main" Repair Center with a page size of 5:
https://{api-url}/v7/workorders?$filter=RepairCenterRef.ID%20eq%20"Main"&$top=5&$skip=10
Ordering of results
Ordering of result sets can be done by appending the OData $orderby keyword. You can order by any element in the result set with ascending or descending order.
Example 1: To retrieve a list of ALL Work Orders ordered by descending Target Hours:
https://{api-url}/v7/workorders?$orderby=TargetHours%20desc
Retrieving all resources
Sometimes you may wish to return a list of all resources from a specific endpoint (eg a full list of Asset Classifications). To do this you simply send a GET request to the resource you are after with no further parameters.
Example 1: To retrieve a list of ALL Classifications:
https://{api-url}/v7/classifications
Result sets will default to a page size of 50 with a maximum of 500. See the information above on paging through result sets for further details.
POST and PUT Methods
Creating resources
The Web API uses POST and PUT requests for creating and editing resources.
- POST requests are used to create new resources and PUT requests are used to edit existing resources
- The Web API will accept resources formatted in JSON
If your request is successful you will receive an HTTP 201 (Created) response and a URI directing you to the new resource in the Location header of the response.
Example 1: To create a single Work Order in the "Main" Repair Center with some additional details specified using JSON:
https://{api-url}/v7/workorders
[
{
"Reason":"Test via API 1",
"RepairCenterRef": {
"PK": 1,
"ID": "M",
"Name": "Main"
},
"RequesterRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"AssetRef": {
"PK": 1,
"ID": "ROOT",
"Name": "Company"
},
"TakenByRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"PriorityDetails": {
"Value": 1,
"Description": "High"
},
"RequestedDate" : "2012-10-05T00:00:00",
"UDFChar1":"test"
}
]
Note that the "Ref" style attributes only need a PK or ID to work so you could use "PK": 1, "ID": "", "Name": "" or "PK": 0, "ID": "ROOT", "Name": "" in the AssetRef above and get the same result.
Creating multiple resources
Multiple resources of the same type can be created by POSTing an array of resources to the desired endpoint URI.
If your request is successful you will receive an HTTP 201 (Created) response.
Example 1: To create a multiple Work Orders in the "Main" Repair Center with some additional details specified using JSON:
https://{api-url}/v7/workorders
[
{
"Reason":"Test multiple via API 1",
"RepairCenterRef": {
"PK": 1,
"ID": "M",
"Name": "Main"
},
"RequesterRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"AssetRef": {
"PK": 1,
"ID": "ROOT",
"Name": "Company"
},
"TakenByRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"PriorityDetails": {
"Value": 1,
"Description": "High"
},
"RequestedDate" : "2012-10-05T00:00:00",
"UDFChar1":"test"
},
{
"Reason":"Test multiple via API 2",
"RepairCenterRef": {
"PK": 1,
"ID": "M",
"Name": "Main"
},
"RequesterRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"AssetRef": {
"PK": 1,
"ID": "ROOT",
"Name": "Company"
},
"TakenByRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"PriorityDetails": {
"Value": 1,
"Description": "High"
},
"RequestedDate" : "2012-10-05T00:00:00",
"UDFChar1":"test"
},
{
"Reason":"Test multiple via API 3",
"RepairCenterRef": {
"PK": 1,
"ID": "M",
"Name": "Main"
},
"RequesterRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"AssetRef": {
"PK": 1,
"ID": "ROOT",
"Name": "Company"
},
"TakenByRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"PriorityDetails": {
"Value": 1,
"Description": "High"
},
"RequestedDate" : "2012-10-05T00:00:00",
"UDFChar1":"test"
}
]
Updating resources
To update a resource you follow the same procedure as you would for creating a single new resource with the following changes:
- The URI must point to the specific resource you wish to update not the resource type
- The HTTP method used is PUT instead of POST
https://{api-url}/v7/workorders/1
{
"Reason":"Test via API 1 - UPDATED",
"RepairCenterRef": {
"PK": 1,
"ID": "M",
"Name": "Main"
},
"RequesterRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"AssetRef": {
"PK": 1,
"ID": "ROOT",
"Name": "Company"
},
"TakenByRef": {
"PK": 44,
"ID": "A",
"Name": "Administrator"
},
"PriorityDetails": {
"Value": 1,
"Description": "High"
},
"RequestedDate" : "2012-10-05T00:00:00",
"UDFChar1":"test"
}
Updating multiple resources
To update multiple resources you follow the same procedure as you would for updating a single resource with the following changes:
- The URI is the same as when creating new records
- The HTTP method used is PUT instead of POST
- The record identifier, PK, must be included in the JSON payload
- The multiple records are enclosed as an array, [ ], the same as creating new records.
https://{api-url}/v7/workorders
[
{
"PK" : 1,
"Reason":"Test via API 1 - UPDATED",
"UDFChar1":"test 1"
},
{
"PK" : 2,
"Reason":"Test via API 2 - UPDATED",
"UDFChar1":"test 2"
}
]