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.
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.
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
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. |