API : Envelopes

Envelopes return a standardize response from all server resources and inside the result of the envelope is the actual data from the server resource.  Each envelope contains information about the returned data record counts, the application, the endpoint, the http status and any errors they may have occurred.

How Envelopes Work

Depending on the requested content type an envelope will return either a JSON or XML output in the body of the response. Regardless of any errors the server resource will alway return and envelope.  If the request was successful, then within the result section of the envelope will be the serialized data of the request.

The envelope also has standard actions which work with all resources, which can help limit the amount of requested data by using pages and page sizes.

Actions

​page={number} - Sets the page number you want the server resource to return.
size={number} - Sets the amount of results you want on each page.
depth={parent/children/grandchildren/greatgrandchildren} - This allows you to select the depth of child resources that are returned in the result(s).
filter={field:value} - Allows you to filter the results.
sortby={field} - Allows you to sort the results by a field.
sortdirection={ascending/descending} - Controllers the order in which the results are returned.

Endpoints

GET https://api-app.openpath.io/v1
Returns the basic information about this API.

Envelope Request
GET /v1 HTTP/1.1
Host: api-app.openpath.io
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

Envelope Response
{
 "organization": "OpenPath, Inc.",
 "application": "OpenPath API",
 "version": "1.1.0.0",
 "copyright": "Copyright ©2016 OpenPath, Inc.",
 "name": "OpenPath Root",
 "description": "This is the root restful application programming interface for the OpenPath application. Unauthorized access is strictly prohibited.",
 "result": null,
 "paging": {
   "count": 0,
   "page": 1,
   "size": 1
 },
 "status": 200,
 "status_message": "OK",
 "errors": null
}

Definitions

Name	Field	Data Type	Description
Organization	organization	text	The OpenPath Organization Name.
Application	application	text	The name of the application API.
Version	verion	text	The version of the API.
Copyright	copyright	text	API copyright information.
Name	name	text	The name of the server resource.
Description	description	text	The description of the server resource..
Result	result	payload	This is the serialized data response of the server resource.
Paging	paging	object(s)	The paging object contains the attributes of the data count and limited data sets if the paging actions are used.
? Count	count	number	The total number of available items in the resource.
? Page	page	number	Of all the pages, the current page of data returned.
? Size	size	number	The number of records returned on a single page.
Status	status	number	The http 1.1 status code of the response, see https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for a complete list of status codes
Status Message	status_message	text	The description of the status code.
Errors	errors	array	If there are one or more errors all the errors will be listed.
? Code	key	string	The OpenPath code of the error.
? Message	value	string	The OpenPath error message.

< Server Resources

Authenticate >