QBOS REST API Documentation (vendor:517090, corporate:506764)

Introduction

This document describes the REST API and resources provided by QBOS. The REST APIs are for developers who want to integrate QBOS into their application and for administrators who want to script interactions with the QBOS server.

QBOS's REST APIs provide access to resources (data entities) via URI paths. To use a REST API, your application will make an HTTP request and parse the response. The request and response formats are JSON. Your methods will be the standard HTTP methods GET, PUT, POST and DELETE.

Because the REST is based on open standards, you can use any web development language to access this API.

Audience

This developer's guide is intended for software developers needing a technical reference for using the QBOS REST API. The information you find in this guide is written by software engineering, and is authoritative on how the API behaves.

Additional resources, information about this guide

Occasionally, we make a mistake in this documentation, or unknowingly break a feature that you depend on. If this has happened to you, we apologize! You can help us fix the issue by contacting us. We appreciate your help.

Getting Started

To place any request in QBOS API application from third party application you need to authenticate user account and set/calculate values for the following request headers: Authorization, x-api-salt, x-api-date-utc. See detail Authentication

URI patterns can be devided into these categories:

Filtering by query string arguments "$filter" and "$limit"

"$filter": SQL "where" clause.
"$limit": numeric value as the max number of records to return.
For example ...?$filter=Preferred_Repairman=2 AND status_id=309 AND image is not null AND Initial_Inspection_Score=0&$limit=20
The following URIs support "$filter" as query string argument: *Potentially any property of a Custom Resource can be used as a filter component.
*It is required that the value of $filter is URL-encoded.
*For "$filter" to work for a Custom Resource the Custom Resource needs to be re-published on or after 04/20/2015.

CRM Service (2.3 Contact API)

Security Service (2.4. Security API)

Forms Service (2.5. Forms API)

ADS Service (2.7. Object Schema API)

BPD Service (2.8. Business Process Design API)

.

Scheduling Service (2.9. Scheduling API)

DCMS Service (2.10. DCMS API)

Tasks Service (2.11. Tasks API)

.

Alert / Note Service (2.12. Alert / Note API)

Process Service (2.13. Process API)

.

ACL Service (2.14. ACL API)

Billing Service (2.15. Billing API)

.

Comments Service (2.16. Comments API)

Work Item Service (2.17. Work Item API)

Complex Data View Service [See usage]

Custom Object Service (2.6. Object Record API)

Authentication

Authentication to the Qbos API is granted through the use of a shared-value hash to populate HTTP headers. The hash is used to authenticate the request provenance as well as the message timing, thus limiting the value of replay attempts. (For greater security, the API may implement a "use server salt" option, in which the API server generates and returns valid random salt to the client, which are then expired when used or after timeout.)

Definitions

  • USER_ID - is the alphanumeric ID used to identify the shared-value hash key. It has no semantic meaning other than identifying the shared key, which is then linked to the underlying user in a many-to-one relation.
  • SHARED_KEY - is the alphanumeric hash key known only to the client and the API server.
  • HTTP_METHOD - is one of the HTTP verbs defined in RFCs 2616, 5789, 3744, and 2518, in UTF-8 uppercase.
  • URI - is the REST URI used to identify the requested resource or collection of resources, in UTF-8.
  • SALT - is an arbitrary alphanumeric string, chosen by the client, from 1...255 characters.
  • ACTION_BODY - is the request payload (usually JSON, but may be an empty string).
  • HASH_TYPE - is 'v1-sha256'
  • CANONICAL_DATE - is the current date/time in UTC in the format CCYYmmDD-HHMMSS-f Example: 20140410-123456-743209
  • CANONICAL_ACTION - is the request details in the format USER_ID|HTTP_METHOD|URI|SALT Example: jsmith@domain.com|GET|qbos-rest/rest/v1/o/person/8788120|ABCDEF12345
  • CANONICAL_HASH_ID is in the format qbos-HASH_TYPE Example qbos-v1-sha256

Hash Rounds

  • Hash_1 = SHA256(CANONICAL_DATE, SHARED_KEY)
  • Hash_2 = SHA256 (CANONICAL_ACTION, Hash_1)
  • Hash_3 = SHA256 (ACTION_BODY, USER_ID)
  • Hash_4 = SHA256 (Hash_3, Hash_2)
  • Hash_5 = SHA256 (CANONICAL_HASH_ID, Hash_4)

Method

The client calculates the above values and sends the following authentication headers to the API server:

  • x-api-salt: SALT
  • x-api-date-utc: CANONICAL_DATE
  • Authorization: Basic Hash_5

The server will calculate the hash for the request, using the shared hash key, and authenticate based on the timestamp and authentication hash. The server reserves the right to return an HTTP 401 to indicate a failed authentication attempt based on either a failed hash or an expiration of the timeout period.

URI patterns

Definitions

  • Corporate - QBOS system license owner
  • Standard resource - QBOS system provides a number of standard resources. (person,organization,address,phone,...)
  • Custom resource - QBOS system may be extended by custom resources: QBOS Applets
  • Vendor Id - Applies to custom resource. Corporate id of a QBOS Applet provider
  • Parent Type - Parent resource type. Type of a standard resource or type of a custom resource in alphabetic or numeric form
  • Parent Id - Parent resource id. Numeric id of a standard resource or numeric id of a custom resource
  • Type - Resource type. Type of a standard resource or type of a custom resource in alphabetic or numeric form
  • Id - Resource id. Numeric id of a standard resource or numeric id of a custom resource
  • Query String - URI query string. Supports filtering, paging, inclusion and sorting arguments where applicable: $filter,$offset,$limit,$sort,$include

Standard Resource URI patterns. https://.../v1/o/...

parent
type		parent
id		 typeId JSON
payload		query
string		 description
POST /v1/o/ RR R R Create a resource
GET /v1/o/ RR Read a resource by id
GET /v1/o/ RR links R O Read resources by parent
PUT /v1/o/ RR R Update a resource
DELETE /v1/o/ OO RR O Delete a resource
R=Required, O=optional, Blank=not applicable

Custom Resource URI patterns. https://.../v1/{vendor_id}/...

vendor
id		 parent
relation
id		parent
id		 typeid JSON
payload		query
string		 description
POST /v1/R R R Create a resource
GET /v1/R RR Read a resource by id
GET /v1/R RR links R O Read resources by parent
GET /v1/R R O Read resources by filter
PUT /v1/R RR R Update a resource
DELETE /v1/R OO RR O Delete a resource
POST /v1/R RR links RR Link a resource of type and id with a parent resource
DELETE /v1/R RR links RR Unlink a resource of type and id from a parent resource
R=Required, O=optional, Blank=not applicable

Custom Resource Metadata URI patterns. https://.../v1/ads/...

parent
type		parent
id		 typeId JSON
payload		query
string		 description
POST /v1/ads/ RR R R Create a resource
GET /v1/ads/ RR Read a resource by id
GET /v1/ads/ RR links R O Read resources by parent
PUT /v1/ads/ RR R Update a resource
DELETE /v1/ads/ OO RR O Delete a resource
R=Required, O=optional, Blank=not applicable

Complex Data View URI patterns. https://.../v1/views/...

type query
string		 description
GET /v1/views/ R
[See types]		 R The value of query string argument {$filter} provides the WHERE predicate for the SQL executed by the request. Any property of the view can be used in {$filter}. The value of {$filter} has to be URL-encoded. If {$filter} in not provided then 1 random record is returned from the view as an example record.
R=Required, O=optional, Blank=not applicable

Error handling

Error Response

  • "status" (number) - The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
  • "title" (string) - A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localisation.
  • "detail" (string) - An human readable explanation specific to this occurrence of the problem.
  • "type" (string) - For future use. - An absolute URI [RFC3986] that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html401-19991224]). When this member is not present, its value is assumed to be "about:blank".
  • "instance" (string) - For future use. - An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

Example
{
		"title":"Not found",
		"status":"404",
		"detail":"Resource of type xxxx ...",
		"type": "about:blank",
		"instance": ""
}

Further development of Error Response is based on: Problem Details for HTTP APIs